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PREFACE 


MANUAL OBJECTIVES 


The purpose of this manual is to familiarize the users of an RSX-1I1M, 
RSX-1LIM-PLUS, or Micro/RSX operating system with the File Control 
Services (FCS) facility provided with the system. 


INTENDED AUDIENCE 


Because the File Control Services described in this manual pertain to 
both MACRO-11 and FORTRAN programs, the reader is assumed to be 
familiar with these languages. Also, because the development of 
programs in an RSX-11M/M-PLUS and Micro/RSX environment requires the 
use of the Task Builder, the reader is also assumed to be familiar 
with the contents of the RSX-11M/M-PLUS and Micro/RSX Task Builder 
Manual. 


STRUCTURE OF THIS MANUAL 


Chapter 1 describes the FCS features available for RSX-11M/M-PLUS and 
Micro/RSX users, and defines some of the terminology used throughout 
the manual. This chapter is vital to understanding the balance of the 
manual. 


Chapter 2 describes the actions you must take at assembly time to 
prepare adequately for all intended file I/O processing through FCS. 
This chapter describes the data structures and working storage areas 
that you must define within a particular program to use any of the 
File Control Services. Until you are thoroughly familiar with this 
chapter, you are advised to postpone reading subsequent chapters. 


Chapter 3 describes the run-time macro calls that allow you _ to 
manipulate files and to perform I/O operations. 


Chapter 4 describes a set of run-time routines that perform I/0 
functions on files, such as reading and writing qPERE OEY entries, and 
renaming or extending files. 


Chapter 5 describes the structure of files for disk, DECtapes and 
Magnetic tapes supported by the RSX-11M/M-PLUS and Micro/RSX systems. 


Chapter 6 describes two collections of object library routines. The 
Get Command Line (GCML) routine and the Command String Interpreter 
(CSI) routine may be linked with the user task to perform operations 
that request command line input. Such input consists of file 
specifications that identify and control the files to be processed by 
your program. 
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Chapter 7 describes the table-driven parser (TPARS), which provides 
you with the means to define and parse command lines in a unique 
user-designed syntax. 


Chapter 8 describes queuing files for printing. You can queue files 
for printing at both the MACRO and subroutine levels. 


Finally, the appendixes provide detailed information to help you 
better understand I/0 operations. Appendix A and Appendix B outline 
the File Descriptor Block (FDB) and the filename block, respectively. 
Appendix C summarizes a number of I/0-related system directives that 
form a part of the total resource management capabilities of the 
RS X-11M/M-PLUS Executive. Through simplified sample programs, 
Appendix D illustrates the use of the macro calls that create and 
initialize the FDB. These sample programs also include some of the 
macro calls used for processing files. Appendix E illustrates’ the 
Structure of the index file of a Files-1l volume. The format and 
content of the file header block, magnetic tape labels, and the 
statistics block are described in Appendixes F, G, and H, 
respectively. The error codes returned by the system are listed in 
Appendix I. Field-size symbols are listed in Appendix J. Appendix K 
lists RSX-11M/M-PLUS FCS library system generation options and 
provides a brief description of each. 


ASSOCIATED MANUALS 
The following manuals may be useful: 
@ RSX-11M/M-PLUS Information Directory and Master Index 
@ RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual 


@e RSX-11M/M-PLUS and Micro/RSX Task Builder Manual 


@ PDP-11 MACRO-11 Language Reference Manual 


In addition, documentation for programming in any of the PDP-1l 
languages may be helpful. 


CONVENTIONS USED IN THIS MANUAL 


Unless otherwise noted, the term "RSX-11" refers to the RSX-11M, 
RSX-11M-PLUS, and Micro/RSX operating systems. 
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SUMMARY OF TECHNICAL CHANGES 


This revision of the RSX-11M/M-PLUS and Micro/RSX I/O Operations 
Reference Manual reflects the following software technical changes and 
additions: 

e Support for logical names, which affects information in this 
manual on file and ANSI magnetic tape specification syntax, 
and filename block routines 

e Support for logical name parsing 

e Support for the CSI$4 command semantic parser 


e Changes in parameters for the FDATSA, FDOPSA, and OPENSx 
macros 


e New information on block locking 

e A new file control routine, .FLUSH (buffer flush) 

e Changes to the C.EXPS user task expansion buffer size offset 
and to the C.CMLD command line descriptor offset in the CSI 
control block 

e Changes to offsets within the File Descriptor Block 

@ New volume label offsets 

e New file header format 

In addition to these changes, the manual has been reorganized to make 
the information more easily accessible to the reader. Appendix C has 


also been revised to include all I/0O-related system Executive 
directives. 
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CHAPTER 1 


FILE CONTROL SERVICES 


This chapter describes the File Control Services (FCS) features 
available for RSX-11/M-PLUS and Micro/RSX users. It defines some of 
the terminology used throughout the manual. FCS enables you to 
perform record-oriented and block-oriented I/O operations, as well as 
additional operations required for file control. Open, close, wait, 
and delete are some of these additional operations. The term FCS as 
used in this manual is a_ substitute for FCSRES, a memory-resident 
library. This memory-resident library contains commonly used routines 
that are linked with your task at task-build time. These routines may 
also be linked with your task from a system object module library 
(SYSLIB.OLB). There are three kinds of FCS: 


@ ANSI - supports ANSI format magnetic tape and big buffers 
@e Non-ANSI - does not support ANSI tape or big buffers 


e Multibuffered - supports ANSI tape, big buffers, and multiple 
buffers 


When your task uses commonly requested functions such as OPENS, which 
opens a file, and CLOSES, which closes a file, the Task Builder 
resolves the address of these routines in FCSRES, thereby eliminating 
these routines from your task image. Thus, commonly used FCS routines 
do not significantly increase the size of your task image. If you do 
not link your task with FCSRES at task-build time, the routines must 
come from SYSLIB and are included in your task image, increasing its 
size. These routines, consisting of pure, position-independent code, 
provide an interface to the file system, enabling you to read and 
write files on file-structured devices and to process files by using 
logical records. 


Your program regards logical records as data units that are structured 
in accordance with application requirements, rather than as physical 
blocks of data on a particular storage medium. To meet the 
application's requirements, FCS allows a collection of data--distinct 
logical records--to be written to a file in a way that enables you’ to 
retrieve the data from the file without having to know the exact 
format in which it was written to the file. FCS, therefore, is 
transparent to your task; records can be read or written in logical 
units that are consistent with particular application requirements. 


To invoke FCS functions from your task or application, your’ task 
issues macro calls to specify desired file control operations. The 
FCS macros are called at assembly time to generate code for specified 
functions and operations. The macro calls provide the system-level, 
file control primitives with the necessary parameters to perform the 
file access operations that you request (see Figure 1-1). 
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Figure 1-1 File Access Operation 


1.1 KEY TERMS USED THROUGHOUT THIS MANUAL 


Listed next are terms used throughout this manual, which have unique 
definitions in the context of FCS operations. 


File Descriptor Block (FDB) 


The data structure that provides FCS with information needed to 


perform I/O operations on a file. The space for this data 
structure is allocated in your program by issuing the FDBDFS 
macro call (see Section 2.3.1.1). Each file to be opened 


simultaneously by your program must have an associated FDB. 
Portions of the FDB, which may be defined by you or the system, 
are maintained by FCS. Assembly-time or run-time macro calls are 
provided for you to initialize the FDB. The format and content 
of the FDB are detailed in Appendix A. 


Filename Block 


The portion of the FDB that contains the various elements of a 
file specification (see the File Specification entry in this 
section) that FCS uses. Initially, as a file is opened, FCS 
fills in the filename block with information that you specify and 
that is taken from the dataset descriptor or the default filename 
block (see the next entry). Section 2.4 describes how FCS fills 
in the filename block from a file specification; the format and 
content of the filename block are described in Appendix B. 


Default Filename Block 


An area allocated within your program by issuing the NMBLKS macro 
call (see Section 2.5.2) that contains the various elements of a 
file specification. You create the default filename block, 
whereas the filename block within the FDB is maintained by FCS. 
You create the default filename block to supply file 
specifications to FCS that are not otherwise available through 
the dataset descriptor (see the next entry). FCS takes these 
file specifications and creates a parallel structure in the FDB 
that contains information that FCS requires during execution time 
in opening and operating on files. 
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Thus, the terms "default filename block" and "filename block" 
refer to separate and distinct data structures. These 
distinctions should be kept in mind whenever these terms appear 
in this manual. These areas are structurally identical, but they 
are created and used differently, and may contain different 
information at different times. 


Dataset Descriptor 


A 6-word block in your program that contains the sizes and_ the 
addresses of ASCII data strings that together constitute a file 
specification (see Section 1.9). This 6-word block, which you 
also create, is described in detail in Section 2.4.1. Unless the 
filename block in the FDB has been initialized, you must provide 
FCS with dataset-descriptor or default filename block information 
before the specified file can be opened. 


Dataset Descriptor Pointer 


File 


File 


1.2 


An address value that points to the 6-word dataset descriptor 
within your program. This address value is stored in the FDB, 
allowing FCS to access a file specification that you created in 
the dataset descriptor. 


Specification 


The unique file identification that names a file, specifies the 
location, and allows it to be explicitly referenced by any task. 
The operating system, or your task, must refer to files by using 
a file specification. The file specification contains specific 
information that must be made available to FCS before that file 
can be opened. See Section 1.9 for a description of a file 
specification. 


Storage Region (FSR) 
An area of memory that you reserve for use in I/O operations (see 


Section 1.7.3). You can allocate this area by issuing the FSRSZS$ 
macro call in your program (see Section 2.7). 


IMPORTANT FCS CHARACTERISTICS 


You should be aware of the following FCS characteristics when using 
its I/O facilities: 


e I/0 operations initiated by READS and WRITES macros are 
asynchronous; you are responsible for coordinating all block 
I/O activity. 


e I/0 operations initiated by GETS and PUTS macros are 
synchronized entirely by FCS; control is not returned to your 
program until the requested GETS or PUTS operation is 
complete. 


e FCS macro calls save and restore all registers, with the 
following exceptions: 


- The file-processing macro calls (see Chapter 3) place the 
File Descriptor Block (FDB) address in RO. 


- Many of the file control routines (see Chapter 4) return 
requested information in the general registers. 
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@e The macro that defines and allocates the space for the File 
Descriptor Block (FDB) is the FDBDFS macro (see Section 
2.3.1.1). Once the FDB is allocated, necessary information 
can be placed in this data construct through any logical 
combination of assembly-time or run-time macro calls (see 
Sections 2.3.1 and 2.3.2, respectively). Certain information 
must be present in the FDB before FCS can open and operate on 
a specified file. 


@e For each assembly-time FDB initialization macro call, a 
corresponding run-time macro call is provided that supplies 
identical information. Although both sets of macro calls (see 
Table 2-1 in Section 2-1) place the same information in the 
FDB, each set does so in a different way. The assembly-time 
calls generate .BYTE or .WORD directives that create specific 
data, while the run-time calls generate MOV or MOVB 
instructions that place desired information in the FDB during 
program execution. 


e If an error condition is detected during any of the 
file-processing operations described in Chapter 3, or during 
the execution of several of the file control routines (see 
Section 4.1), the Carry bit in the Processor Status Word is 
set, and an error indicator is returned to FDB offset location 
F.ERR. 


NOTE 


When you use the READS or WRITES macros to execute 
system I1/0, the IOSB parameter must be specified for 
F.ERR and the Carry bit to be properly returned (see 
Section 3.15). 


If the address of a user-defined error-handling routine is specified 
aS a parameter in any of the file-processing macro calls, a JSR PC 
instruction to that error-handling routine is generated. The routine 
is then executed if the Carry bit in the Processor Status Word is set. 


1.3 FCS DATA STRUCTURES 


In addition to generating calls to FCS subroutines, FCS macros’ issued 
by your task create and maintain certain data structures that file I/0 
operations require. These required data structures include the 
following: 


e A File Descriptor Block (PDB) that contains information 
necessary for processing the file. 


e A dataset descriptor that FCS accesses to obtain ASCII file 
name information required to open a specified file. 


e A default filename block that FCS accesses to obtain default 
file name information to open a specified file. FCS accesses 
the default filename block when complete file information is 
not specified in the dataset descriptor. 


e A file storage region (FSR) that FCS uses for working storage. 
The FSR is described in Section 1.3.3. 
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1.3.1 File Descriptor Block (FDB) 


The File Descriptor Block (FDB) contains information that FCS uses’ to 
open and process files. One FDB is required for each file that your 
program opens simultaneously. You initialize some portions of the FDB 
with assembly-time or run-time macro calls, and FCS maintains other 
portions. Each FDB has five sections that contain information that 
your task or the system defines: 


e File attribute section 

@ Record or block access section 
e File open section 

e Block buffer section 

e Filename block portion 


The information stored in the FDB depends upon the characteristics of 
the file to be processed. The FDB and the macro calls that cause 
values to be stored in this structure are described in detail in 
Section 2.3. Appendix A describes the format and the content of the 
FDB. 


1.3.2 Dataset Descriptor and Default Filename Block 


You must specify either a dataset descriptor or a default filename 
block for each file that you intend to open. These data structures 
provide FCS with the file specifications required for opening a_ file. 
Although either the dataset descriptor or the default filename block 
is usually specified, you may also specify both for the same file. 
The dataset descriptor and the default filename block are further 
described in detail in Sections 2.5.1 and 2.5.2. 


When a file is being opened using information already present in the 
filename block, neither the dataset descriptor nor the default 
filename block is accessed by FCS for required file information. This 
method of file access, which is termed "opening a file by file ID" is 
an efficient means of opening files. Section 2.6 describes this 
process in detail. 


1.3.3 File Storage Region (FSR) 


The file storage region (FSR) is an area allocated in your program as 
working storage for record I/O operations (see Section 1.7). The FSR 
consists of two program sections that are always contiguous. These 
program sections exist for the following purposes: 


SSFSR1 - This area of the FSR contains the block buffers and the 
block buffer headers for record I/O processing. You 
determine the size of this area at assembly time by 
issuing the FSRSZ$ macro call (see Section 2.7). The 
number of block buffers and associated headers is based 
on the number of files that you intend to open 
simultaneously for record I/O operations. 
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SSFSR2 - This area of the FSR contains impure data that FCS uses 
and maintains when performing both record and block I/0 
operations. Portions of this area are initialized at 
task-build time, and other portions are maintained by 
FCS. 


The size of the FSR can be changed, if desired, at task-build time. 
Section 2.8 shows you how to do this. 


1.4 FILE ACCESS METHODS 


RSX-11M/M-PLUS and Micro/RSX systems support both sequential and 
random access to data in files on sequential access devices (such as 
magnetic tapes and card readers) and random access devices (such as 
disks). The sequential access method is device independent; that is, 
sequential access is usable on both record-oriented and random access 
devices (for example, card reader and disk). You can use the random 
access method only for random access devices. 


1.5 DATA FORMATS FOR FILE-STRUCTURED DEVICES 


Data is transferred between peripheral devices and memory in blocks. 
A data file consists of virtual blocks, each of which may contain one 
or more logical records created by your program. In FCS terms, a 
virtual block in a file consists of 512(decimal) bytes for random 
access devices. The size of the logical records in the virtual blocks 
is under the control of the program that originally wrote the records. 


When creating a new file, your program can specify that the records in 
the file will differ in size. Such records are known as 
variable-length records. Conversely, if your program indicates that 
all records in the new file will be equal in size, the records are 
known as fixed length. 


There are two types of variable-length records: sequenced and 
nonsequenced. Both must be word aligned. Sequenced variable-length 
records are preceded by a 2-word record header. The first word 


contains the length of the record, and the second word contains the 


value of the sequence number: 
n-2 bytes of data 


16 16 
Byte Count|Sequence Number 


Nonsequenced variable-length records are preceded by a_ single-word 
record header containing the length of the record: 


16 


Both fixed- and variable-length records are aligned on a_ word 
boundary. Any extra byte that results from an odd-length record is 
simply ignored. (The extra byte is not necessarily a 0 byte.) 
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Virtual blocks and logical records within a file are numbered 
sequentially, each starting at 1. A virtual block number is a file 
relative value, whereas a logical block number is a volume relative 
value. Ordinarily, records may cross’ block boundaries. Crossing 
block boundaries means that the beginning of a record can fill out the 
end of a block, while the rest of the record occupies the beginning of 
the next block. 


1.5.1 Data Formats for ANSI Magnetic Tape 


You can use both fixed- and variable-length records on magnetic tape; 
their format conforms to the ANSI standard. 


On magnetic tape, a virtual block corresponds to a physical record. 
The default length of a block is 512 bytes. Its length can be changed 
to any value from 8 through 2048 bytes (14 through 2048 bytes for a 
write function) with the use of the FDBFS$ macro (see Section 2.3.1.6). 
Records are not allowed to cross block boundaries. 


Fixed-length records are packed into a block with no control 
information and no padding for alignment. The block is truncated so 
that it ends at the word boundary immediately following the last 
record that will fit in the block buffer. 


Variable-length records are preceded by a 4-byte count field, 
expressed in decimal in ASCII characters. The count includes the 
length of the record and the 4-byte count field. After the last 
record in a block (if there is any space left in the block), a caret 
character ("“", ASCII code 136) appears where the next byte count 
should be, signaling the end of data in that block. 


1.6 BLOCK I/O OPERATIONS 


Block I/O operations provide an efficient means of processing file 
data, because such operations do not involve the blocking and 
deblocking of records within the file. Also, block I/0 operations 
permit your task to read or write files in an asynchronous manner; 
that is, control may be returned to your program before the requested 
I/O operation is completed. 


The read and write macro calls (READS and WRITES) allow your task _ to 
read and write virtual blocks of data to and from a file without 
regard to logical records within the file. (See Sections 3.15 and 
3.16 for a description of READS and WRITES macro calls.) When your 
task uses block I/0, the number of the virtual block to be processed 
is specified as a parameter in the appropriate READS or WRITES macro 
call. The virtual blocks so specified are processed directly in a 
reserved buffer in your task's memory space. Your task can use READS 
and WRITES only on block-structured devices. 


You are responsible for synchronizing all block I/O operations. Such 
asynchronous operations can be coordinated through an event flag (see 
Section 2.9.1) specified in the READS/WRITES macro call. The system 
uses the event flag to signal the completion of a specified block I/0 
transfer, enabling you to coordinate those block I/O operations’ that 
are dependent on each other. 
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1.7 RECORD I/0 OPERATIONS 


Sequential access mode I/O operations can be performed for both 
fixed- and variable-length records. Random access mode I/O operations 
can be performed only for fixed-length records. Your program accesses 
records randomly by specifying a record number. This number 
represents the position of the desired record within the file (viewing 
the file as an array of fixed-sized records, with the number 1 
representing the first record physically present in the file, and n 
the last). 


The GETS and PUTS macro calls (see Sections 3.9 and Se12, 
respectively) are provided for processing individual records in files. 
Using the FSR block buffers (see Section 1.3.3), the GETS and pPuUTS 
routines perform the necessary blocking and deblocking of records 
within the virtual blocks of the file, allowing your program to access 
logical records. Successive GETS$ or PUTS operations in random access 
mode can access records anywhere within the file. To do so, your 
program need only modify the record number specified as part of the 
random record operation. After each such random operation, FCS 
increases by one the record number used in the operation. If your 
program does not again modify this number prior to issuing another 
record operation, the record actually accessed is the next sequential 
record in the file. 


In contrast to block I/O operations, all record I/0 operations are 
synchronous; that is, control is returned to your program only after 
the requested I/O operation is completed. 


Because GETS or PUTS operations process logical records within a 
virtual block, only a limited number of GETS or PUTS operations result 
in an actual I/O transfer (for example, when the end of a data block 
is reached). Therefore, all GETS or PUTS I/O requests’) do not 
necessarily involve an actual physical transfer of data. 


The data flow during record I/O operations is shown in Figure 1-2. 
Note that blocks of data are transferred directly between the FSR 
block buffer and the device containing the desired file. The 
deblocking of records during input occurs in the FSR block buffer, and 
the blocking of records occurs in the FSR block buffer during output. 
Note also that FCS serves as your task's interface to the FSR block 
buffer pool. All record I/O operations, which are initiated through 
GETS and PUTS macro calls, are synchronized by FCS unless 
multibuffering is in use. 
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Figure 1-2 Record I/0 Operations 


1.7.1 Record I/O Data-Transfer Modes 


By using record I/0, a program can gain access to a record in either 
of the two following ways after the virtual block has been transferred 
into the FSR from a file: 


@e In move mode, by specifying that individual records are to be 
moved from the FSR block buffer to a record buffer that you 
have defined (see Figure 1-2) 


@e In locate mode, by referencing a location in the File 
Descriptor Block (see Section 1.3.1) that contains a pointer 
to the desired record within the FSR block buffer 


1.7.1.1 Move Mode - Move mode requires that data be moved between the 
FSR block buffer and a record buffer that you have defined. For 
input, data is first read into the FSR block buffer from a peripheral 
device and then moved to your task's record buffer for processing. 
For output, your program builds a record in your task's record buffer; 
FCS then moves’ the record to the FSR block buffer, from which it is 
written to a peripheral device when the entire block is filled. 


Move mode simulates the reading of a record directly into your task's 
record buffer; thus the blocking and deblocking of records is 
transparent. 
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1.7.1.2 Locate Mode - Locate mode enables your task to access records 
directly in the FSR block buffer. Consequently, there is normally no 
need to transfer data from the FSR block buffer to your task's record 
buffer. To access records directly in the FSR block buffer, refer to 
locations in the File Descriptor Block (see Section 1.3.1 and Appendix 
A) that contain values defining the length and the address of the 
desired record within the FSR block buffer. These values are present 
in the FDB as a result of FCS macro calls that you issued. 


Program overhead is reduced in locate mode because records can be 
processed directly within the FSR block buffer. Moving data to your 
task's record buffer in locate mode is required only when the last 
record of a virtual block crosses block boundaries. 


1.7.2 Multiple Buffering for Record I/O 


By supporting multiple buffers for record I/0, FCS provides’ the 
ability in multibuffered FCS (see Appendix K) to read data into 
buffers in anticipation of user program requirements, and to write the 
contents of buffers while your program is building records for output. 
You can thus overlap the internal processing of data with file I/0 
operations, as illustrated in Figure 1-3. 


When your task uses read-ahead multiple buffering, the file must be 
sequentially accessed to derive full benefit from multiple buffering. 
For write-behind multiple buffering, you can use any file access 
method with full benefit. 


When your task uses multiple buffering, you must allocate sufficient 
space in the FSR for the total number of block buffers in use at any 
given time. The FSRSZS macro call (see Section 2.6.1) allocates space 
for FSR block buffers. 


Time 

Single process record write record process record write record arene’ 
Buffer 

Multiple process record write record process record write record 

Buffer process record write record process record ae 
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Figure 1-3 Single Buffering Versus Multiple Buffering 


1.7.2.1 Multiple Buffering Performance - Multiple buffering can 
improve performance for I/0-bound tasks under certain circumstances. 
However, multibuffer processing in random mode is not very efficient. 
When using multibuffering in random mode, a user record buffer is 
always required. If one is not supplied, the task's low memory may be 
overwritten and the task may abort. 
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For example, consider an I/O-bound task running as the dedicated or 
highest priority application on a system. For such a task, multiple 
buffering can decrease execution time by enabling overlap of I/O and 
task execution. 


However, if other tasks run at the same priority as that of the 
application task described previously, then an overlap of I/O and task 
execution is already achieved among these tasks without multiple 
buffering. In this case, multiple buffering would use up address 
space and pool without improving execution speed. If virtual and 
physical address space is available, big buffering would improve 
performance (see Section 1.7.3). However, big buffer processing in 
random mode is not very efficient. 


1.7.3 Big Buffering for Record I/O 


If the task uses large records or operates on clusters of records, big 
buffering is advantageous. The use of big buffering assumes that it 
is reasonable to use more task address space and physical memory for 
increased buffer space, and more pool for the increased number of 
outstanding I/O packets. 


Big buffering reduces the number of disk accesses by allowing 
multiblock input and output. Normally, the disk accesses for GETS or 
PUTS operations are performed one sector at a_ time. Using FCS big 
buffers allows you to read or write a specified number of sectors ina 
single operation. 


When using big buffering in random mode, a user record buffer is 
always required. If one is not supplied, the task's low memory may be 
overwritten and the task may abort. Using big buffering with random 
GETS and PUTS can cause data to be lost from the end of a file. In 
this case, a directory of the file would indicate more blocks in use 
than it had allocated. To prevent this condition from happening, 
follow these steps: 


@e Preallocate enough space to make writing an extension 
unnecessary. 


e Execute a FLUSH operation after the highest-numbered record is 
written by a PUTS macro. 


e After a PUTS macro, arrange not to execute any GETS macro that 
could cause the file to extend. 


To use big buffers, you must select the buffer size and specify that 
buffer size in the parameter lists for each occurrence of both the 
FSRSZ$ macro and the FDBDFS$ macro in your program. 


You should choose a buffer size that is a multiple of 512(decimal) 
bytes, the size of one disk block. Because the default amount 
allocated by a file extend is five blocks and disks often contain many 
5-block files or parts of files, a buffer size of five blocks is 
generally a good choice. Larger amounts may increase performance, but 
note that you are trading large amounts of memory for speed. 


You must reserve the buffer space in your program and you must specify 
the buffer size to the FDB. The FSRSZS macro allows you to specify 
the total buffer space needed. Specify 512(decimal) bytes for each 
normal disk file, plus the buffer size that you have selected for each 
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big buffered file. For example, assume that a program has’ three 
files: one normal file (512-byte buffer); one file with a big buffer 
size of three blocks; and one file with a big buffer size of five 
blocks. The following call to the FSRSZS macro reserves the space 
properly: 


FSRSZ$ 3,<<14+3+5>*512.> 


In the FDB of each file that has a big buffer, you must override the 
default buffer size, using either the FDBFSA macro or the FDBFSR 
macro. For a file with five blocks as a big buffer, the assembly-time 
macro call is: 


FDBFSA- ,<5*512.> 


On RSX-11M-PLUS and Micro/RSX systems, the SYSLIB provided as. the 
default library contains all the proper FCS modules for big buffer 
Support. RSX-11M user tasks must link to ANSLIB for these modules. 


1.8 SHARED ACCESS TO FILES 


The Files-l1l disk architecture permits shared access to files 
according to established conventions. You can issue one of two macro 
calls, among several available in FCS for opening files, to invoke 
these conventions. The OPNSSx macro call (see Section 3.2) 
specifically opens a file for shared access. The OPENSx macro call 
(see Section 3.1), on the other hand, invokes generalized open 
functions that have shared-access implications only in relation to 
other I/O requests subsequently issued. Both macro calls take an 
alphabetic suffix that specifies the type of operation being requested 
for the file, as follows: 


R - Read existing file 


W - Write (create) a new file 

M - Modify existing file without extending its length 

U - Update existing file and extend its length, if necessary 
A - Append data to end of existing file 


The suffix R applies to the reading of a file, whereas the suffixes W, 
M, U, and A all apply to the writing of a file. You can use the 
OPNSSx and OPENSx macro calls as follows for shared access to files: 


1. When the OPNSSR macro call is issued, read access to the file 
is granted unconditionally, regardless of the presence of one 
or more concurrent write-access requests to the file. (The 
OPNSSR macro call permits concurrent write accesses to the 
file while it is being read.) Subsequent write-access 
requests for this same file are honored. Thus, several 
active read-access requests and one or more write-access 
requests may be present for the same file. However, multiple 
tasks simultaneously accessing the file for write operations 
are subject to certain restrictions, as detailed in number 2. 


2. While FCS allows concurrent write-access requests through the 
use of the OPNSSW, OPNSSM, OPNSSU, and OPNSSA_ macro, 
synchronizing access to the file is your task's 
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responsibility. To avoid the retrieval or storage of 
inconsistent data, each task must implement and use some 
mechanism, which you define, ensuring that the file is 
serially accessed. 


3. When the OPENSR macro call is issued, read access to the file 
is granted, provided that no write-access requests for that 
file are active. (The OPENSR macro call does not permit 
concurrent write access to the file while it is being read.) 


Note from the previous text that readers of a shared file should be 
aware that the file may yield inconsistent data from request to 
request if that file is also being written. 


Shared access during reading does not necessarily mean that the access 
requests are all from separate tasks. A file could also be shared by 


a single task that has opened the file on several different logical 
unit numbers. 


Table 1-1 shows the circumstances under which Files-ll permits a 
second file access when the file is opened for shared access. 


Table l-l 
Shared File Access 


First Access 


Second Access Read Shared read Write Shared write 


Read Yes Yes No No 
Shared 
Read Yes Yes Yes Yes 
Write No Yes No No 
Shared 
Write No Yes No Yes 


1.9 FILE SPECIFICATION SYNTAX 


A full file specification has the following elements, in the order 
listed: 


device 
directory 
name 
type 
version 
A file specification has the following format: 
device: [directory] filename. filetype; version 


An example of a full file specification follows: 


LB: [1,*]SUPLIB.OLB;0 is a full file specification. 
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1.9.1 Device 
The device element of the file specification names the device on which 
the file resides. For unit-record devices, such as terminals and line 
printers, this is the only significant element in the file 
specification. 
Except for logical names, the device specification consists of two 
alphabetic characters specifying the device name, followed by 0- to 
3-character octal numeric string specifying the device unit number, 
followed by a colon (:). FCS converts lowercase alphabetic characters 
to uppercase before passing them to the operating system. The device 
unit number must not exceed 377 octal; if no unit number is given, FCS 
assumes unit 0. 
For example: 

db2: and DBO2: are equivalent device specifications. 

SY: and sy00: are equivalent device specifications. 


login: and LOGIN: are equivalent logical device specifications. 


1.9.2 Directory 

The directory element of the file specification names the directory 
through which the file can be found on the device. For ANSI magnetic 
tape files, this element is not significant (see Section A.2). 


If you use numbered directories, the directory specification can take 
either of the following forms: 


[group,member ] 

or 

<group,member> 
Note that the delimiting characters ([] or <>) and the comma (,) must 
appear as shown. The group and member subelements each consist of a 
l- to 3-digit octal number in the range of 0O to 377 octal. In 
situations where wildcards are permitted, you can substitute a single 
asterisk (*) character for the group or member subelement, or both, to 
indicate that all such elements are acceptable. 


You can explicitly request the current default directory by specifying 
[] or <> as the directory specification. 


The following are equivalent directory specifications: 
[27,36] or <027,036> 

The following show the use of various wildcard substitutions: 
([27,*] indicates all members in group 27. 
{[*] indicates all directories. 


[] indicates the current default directory. 
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If you use named directories, the directory specification can take any 
of the following forms: 


([nmamenamen] or <namenamen> 
or 
[001009036] or <001009036> 
or 
[name09030] or <name09030> 


Note that the delimiting characters ([{] or <>) must appear as_ shown. 
The name may consist of as many as nine characters. The characters 
must be only the 36 alphanumeric characters from A through Z and 0 
through 9. In situations where wildcards are permitted, you can 
Substitute a single asterisk (*) character for the named directory. 


1.9.3 Name 


The name element of the file specification is the name by which the 
file is known in the directory. The name specification is a 0- to 
9-character alphanumeric string. That is, the alphabetic characters A 
to Z, the numbers 0 to 9, the underscore (_), and the dollar Sign (S$) 
are all allowed. FCS converts lowercase alphabetic characters’ to 


uppercase before passing them to the operating system. 


In situations where wildcards are permitted, you can substitute an 
asterisk (*) character in the name string for any string including the 
null string. 


For example, the following names are acceptable within a file 
specification: 


MyFile.; is interpreted as MYFILE.. 
*.3; matches all names. 


-; is interpreted as the null name of 0 length. 


1.9.4 Type 


The type element of the file specification is the type by which the 
file is known in the directory. The type specification consists of a 
period (.) followed by a O0- to 3-character alphanumeric string. FCS 
converts the lowercase alphabetic characters to uppercase before 
passing them to the operating system. In situations where wildcards 
are permitted, you can substitute asterisk (*) characters for any 
string including the null string. 


The following examples show some of the conversions that FCS makes: 
dat is interpreted as .DAT 
om is interpreted as all types 


: is interpreted as the null type 
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1.9.5 Version 


The version element of the file specification provides the version 
number by which the file is known in the directory. The version 
specification consists of a semicolon (;) followed by a 0- to 5-digit 
octal number in the range of 0 to 77777. 


NOTE 


On RSX-11M-PLUS and Micro/RSX systems, decimal numbers 
are a system generation option. Decimal numbers can 
range from 0 through 32767. 


In situations where wildcards are permitted, you can substitute a 
single asterisk (*) character for the octal number to indicate that 
all versions are acceptable. In situations where you are specifying a 
file that already exists, you can substitute the two characters "-1" 
for the octal number to specify the lowest-numbered version of the 
file that is known to the directory. 


You can specify a version number of 0 or the null version to indicate 
either of the following: 


e The highest-numbered version of the file that is known to. the 
directory, when the file already exists 


@e A version number one greater than the highest-numbered version 
of the file (if any) known to the directory, when you are 
creating a new directory entry 


The following show some conversions that FCS makes regarding version 
numbers: 


75 and ;0005 are equivalent versions. 
;* indicates all versions. 
7-1 indicates the lowest-numbered version. 


indicates the null version; this is equivalent to ;0. 


=e 


For compatibility with other systems, FCS access methods can process 
version specifications beginning with a period (.) instead of 
semicolon (;) when the presence of a type specification eliminates 
ambiguity. 


1.10 ANSI MAGNETIC TAPE FILE SPECIFICATION SYNTAX 


The file specification format specific to magnetic tapes consists of 
the following elements, in the order listed: 


device 
directory 


quoted string 
version 


1.10.1 Device 


The device element is the same as that described in Section 1.9.1. 
The device must be a magnetic tape device. 


1-16 
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1.10.2 Directory 


The directory element is the same as that described in Section 1.9.2. 
This element has no meaning for ANSI magnetic tape files, and it is 
ignored if present. 


1.10.3 Quoted String 


FCS treats a quoted string as a unit representing both the name _ and 
type elements of a standard file specification. This mechanism allows 
expression of tape file names up to 17 characters in length that 
include the full set of ANSI "a" characters (some of which would 
otherwise be ignored or treated as element delimiters in a_ standard 
file specification). 


You specify an ANSI name by including the name in quotation characters 
("name"). If the name itself contains full quotation characters ("), 
you must also precede each such character with an additional full 
quotation character ("). FCS converts any lowercase alphabetic 
characters to uppercase, strips the full-quotation characters that you 
have added, and passes the result to the operating system without 
further modification (including ANSI "a" characters such as SPACE). 


The following examples show the results of FCS-processed quoted 
strings: 


"My File" is interpreted as MY FILE. 


"""Don't Panic""" is interpreted as "DON'T PANIC", 


1.10.4 Version 


The version element of a magnetic tape file specification is the same 
as that for a conventional file specification (see Section 1.9.5). A 
version specification of ;0, ;-l, or the null version, is interpreted 
as any version for magnetic tape files. 


1.10.4.1 Example Magnetic Tape File Specification - An example of an 
ANSI magnetic tape file specification follows: 


MM1:"MULP's file" specifies any version of MULP'S FILE on device MM1: 


The standard file specification format described in Section 1.9 can 
also be used with magnetic tapes; this permits file transport to 
nontape devices and file accessibility by the widest possible range of 
software. See Appendix G of this manual for additional information 
concerning the use of names in ANSI magnetic tape files. 


1.11 GENERATION OF A FULL FILE SPECIFICATION 


When you specify the target file for an FCS operation, FCS generates a 
full file specification in the following manner: 


1. FCS parses the filename string to determine which elements 
are present. You need not provide a full file specification 
in the filename string; however, any elements present must be 
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syntactically correct and in the proper order. FCS ignores 
any NULL, SPACE, or TAB characters that may be present in the 
string unless they occur within an ANSI magnetic’ tape 
quoted-string name. 


2. FCS processes the default name block to determine which 
elements are present. You need not provide a full file 
specification in the default name block. 


3. If the filename string does not provide a full file 
specification, FCS obtains missing elements from the default 
name block; if any elements are lost as a result of this 
merge, FCS provides default values for them as follows: 


- Device -- defaults to the device to which the specified 
logical unit is currently assigned; if the specified 
logical unit is not assigned to any device, defaults’ to 


SY: 
- Directory -- defaults to the current directory 
- Name, type, version -- defaults to null 


1.12 LOGICAL NAMES 

A logical name is a name that you or the system defines for: 
e All or part of a file specification 
e A physical device 


To keep your program and command procedures independent of physical 
file specifications, you can substitute a logical name for all or part 
of a file specification, either interactively or from within a program 
or command procedure. 


A logical name may contain 1 through 63 alphanumeric characters, 
including the special characters dollar sign ($) and underscore (_). 


A logical name must have an entry in the logical name table. 


If the first character of the logical name is an underscore (_), the 
translation process that replaces the logical name with its equivalent 
string removes the underscore only. Thus, the input string is not 
translated, the translation stops, and the resultant string remains. 


A logical name may be a device name or a file name. If a logical name 
is a device name, it must be terminated by a colon (:). 


You can assign logical names to devices such as tape drives, 
terminals, and line printers. The system manager may assign logical 
names to public disk volumes, so that you do not have to be concerned 
with the physical location of those volumes. 


In addition, to reduce typing you can use logical names as a shorthand 
way of specifying files or directories that you refer to frequently. 
For example, you might assign the logical name HOME to your task's 
default disk and directory. 
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1.12.1 Using Logical Names for Program Input and Output 


Programs that read and write data can be designed to read from or 
write (perform 1/0) to different files or devices each time they are 
run. Performing 1/0 to different files or devices at different times 
is called device and file independence and is accomplished through the 
use of logical names. 


When you write a program, you can refer to an input or output file by 
using a logical name. For instance, you might use INFILE to represent 
the data file or input device from which the program is to read, and 
OUTFILE to represent the file or device to which the program is to 
write. After your program is compiled and linked, but before it is 
run, you use system commands to associate the logical names you used 
in the program and the actual files or devices you want to use when 
you run the program. 


The DEFINE and ASSIGN commands associate the logical names with the 
files or devices. They establish the correspondence between a logical 
name (that is, the name that you used in the program) and an 
equivalence name (that is, the actual file or device name that you 
want the program to use). 


1.12.1.1 Logical Name Tables - The system maintains logical name and 
equivalence name pairs in three logical name tables. 


e User logical name table -- contains logical name entries’ that 
are local to a particular task. By default, the DEFINE and 
ASSIGN commands place a logical name in the user logical name 


table. 
@e Group logical name table -- contains logical name entries that 
are qualified by a group number. These entries can be 


accessed only by tasks that execute with the same group number 
in their user identification codes (UICS) as the task that 
assigned the logical name. 


e System logical name table -- contains entries that can be 
accessed by any task in the system. 


1.12.1.2 Specifying Logical Names - Logical names and their 
equivalence name strings can have a maximum of 63 characters, and can 
form all or part of a file specification. If only part of a file 
specification is a logical name, it must be the leftmost component of 
the file specification. You can then specify the logical name in 
Place of the device name or device and directory name in subsequent 
file specifications. A logical name can contain both a device name 
and a directory name. 


The equivalence name for a logical name must contain the proper 
punctuation for a file specification (colons, brackets, periods). If 
the equivalence name is a device name, it must be terminated by a 
colon (:). 


Logical name translation is discussed in Chapter 4. 
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1.13 ROUTINES INCLUDED IN FCSRES 
The following lists the routines contained in all 
However, the routines included in 


placed into two overlay segments. 


forms of FCS. 


the overlaid version FCSRES are 


The first overlay segment for open, 


close, and associated user-accessible routines includes: 


Routine Name 


ASCII UIC to Binary Conversion 

Assign Logical Unit Number 

Binary UIC to ASCII Conversion 

Close 

Delete File 

Delete File by File Name Block 

Directory Primitives 

Extend File 

Expand Logical Name and Return 
Pointer to Expanded String 


File Storage Region Initialization 


Get Directory 
Get Directory ID 
Mark for Deletion (Internal) 


Mark for Deletion (User Interface) 


Octal to Decimal Conversion 
Open 

Parse 

Parse Device 

Parse Directory 

Parse File Name 

Print 

Rename 

Request Logical Core Block 


Send Data to and Start a Subsidiary Task 


Truncate and Close File 
User Directive Primitives 


The second overlay for get, 
user-accessible routines includes: 


Routine Name 
Arithmetic Routines 


ASCII to Binary Conversion 
Binary to ASCII Conversion 


Convert Double Precision to Decimal 
Double Precision Arithmetic Routines 


Edit Message 

Edit Time and Date 

Exit With Status 

Read/Write File Storage Region 2 
Flush 

Get Record 

Obtain Library Attributes 

Octal to Binary Conversion 

Parse Command Line 


Point and Mark 

Position Record 

Put Record 

QIO 

Read Block 

Return Position 

User Device Control Function 
Wait 

Write Block 


put, 


Module Name 


ASCPPN 
ASSLUN 
PPNASC 
CLOSE 
DELJMP, 
DEL 
DIRECT 


EXTEND 


.EXPLG 
FINIT 
GETDIR 
GETDID 
MKDL 
MRKDL 
.ODCVT 
OPNJMP, 
PARSE 
PARSDV 
PARSDI 
PARSEN 
SPRINT 
RENAME 
RQLCB 
DSPAT 
TRNCLS 
UDIREC 


read, 


write, 


DELETE 


OPENR 


and other 


Module Name 


ARITH 
CATB 
CBTA 
CODMG 
DARITH 
EDTMG 
EDDAT 
EXST 
RWFSR2 
FLUSH 
GETIMP, 
FCSTYP 
.OD2CT 
-CSI1, 
.CSI4, 
PNTMRK 
POSREC 
GETJMP, 
XQIOU 
READ 
POSIT 
CONTRL 
WAITU 
WRITE 


GET 


-CSI2, 
-EXPLG 


PUT 


CHAPTER 2 


PREPARING FOR I/0 


This chapter describes the macro calls that your task must invoke to 
provide the necessary file-processing information for the file 
descriptor block (FDB). 


2.1 PREPARING FOR I/O -- GENERAL INFORMATION 


The MACRO-11 programmer must establish the proper data base and 
working storage areas within the particular program to perform 
input/output operations. You must do the following: 


1. Define a File Descriptor Block (FDB) for each file that your 
program is to open simultaneously (see Section 2.2). 


2. Define a dataset descriptor and a default filename block, or 
both (see Sections 2.5.1 or 2.5.2, respectively) if you 
intend to access these structures to provide file 
specifications that FCS requires. 


3. Establish a file storage region (FSR) within the program (see 
Section 2.6). (The initialization procedures for FORTRAN 
tasks are described in detail in the PDP-11 FORTRAN-77 User's 
Guide.) 


Your task can place such information in the FDB in one of three ways: 


e By the assembly-time FDB initialization macro calls (see 
Section 2.3.1) 


e By the run-time FDB initialization macro calls (see Section 
2.362) 


e By the file-processing macro calls (see Chapter 3) 


Data supplied during the assembly of the source program establishes 
the initial values in the FDB. Data supplied at run time can either 
initialize additional portions of the FDB or change values established 
at assembly time. Similarly, the data supplied through the 
file-processing macro calls can either initialize portions of the FDB 
or change previously initialized values. 


Table 2-1 lists the macro calls that generate FDB information. 
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Table 2-1 
Macro Calls Generating FDB Information 


Assembly-Time FDB Run-Time FDB File-Processing 
Macro Calls Macro Calls Macro Calls 
FDBDFS$ (Required) FDATSR OPENS (all variations) 
FDATSA FDRCSR CLOSES 
FDRCSA FDBKSR GETS (all variations) 
FDBKSA FDOPSR PUTS (all variations) 
FDOPSA FDBFSR READS 
FDBF SA WRITES 

DELETS 

WAITS 


2.2 .MCALL DIRECTIVE -— LISTING NAMES OF REQUIRED MACRO DEFINITIONS 


You must list as arguments in an .MCALL directive all the 
assembly-time, run-time, and file-processing macro calls (see Table 
2-1) that you intend to issue in a= program. Doing so allows’ the 


required macro definitions to be read in from the system macro library 
during assembly. 


You must write the .MCALL directive and associated arguments in the 
program prior to writing any macro call in the execution code of the 
program. If the list of macro names is lengthy in the .MCALL 
statement, you must specify several .MCALL directives, each appearing 
on a separate source line. The availability of space within an 
80-byte line of source code limits the number of such names that may 
appear in any one .MCALL statement. 


Format 

e-MCALL argl,arg2,...,argn 
Arguments 
argl,arg2,...,argn 


A list of symbolic names that identify the macro definitions that 
you use in your. program. If more than one source line is 
required to list the names of all desired macros, each additional 
line must begin with an .MCALL directive. 


For clarity in your source code, you may list the assembly-time, 
run-time, and file-processing macro names in each of three 
separate .MCALL statements; you may list the macro names 
alphabetically, or mix them. None of these optional arrangements 
have any effect whatever on retrieving macro definitions from the 
system macro library. 


If you are planning to invoke the command line processing 
capabilities of the Get Command Line (GCML) routine and the 
Command String Interpreter (CSI), you must list all the names. of 
the associated macros as arguments in an .MCALL directive. GCML 
and CSI, ordinarily employed in system or application programs 
for convenience in dynamically processing file specifications, 
are described in detail in Chapter 6. 
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The .MCALL directive is described in detail in the PDP-1ll MACRO-11 
Language Reference Manual. The sample programs in Appendix D also 
illustrate the use of the .MCALL directive. Note that these .MCALL 
directives appear as the first statements in the preparatory coding of 
these programs. 


The object routines described in Chapter 4 should not be confused with 
the macro definitions available from the system macro library. The 
file control routines, constituting a body of object modules, are 
linked into your program at task-build time from the system object 
library ([{1,l1]SYSLIB.OLB). Consult Section 4.1 for a description of 
these routines. 


The following statements show sample uses of the .MCALL directive: 


-MCALL FDBDFS,FDATSA,FDRCSA,FDOPSA,NMBLKS$,FSRSZS$,FINITS 
-MCALL OPENSR,OPENSW,GETS, PUTS$,CLOSES 


NOTE 


You can use the macro FCSMCS to declare the most 
commonly used FCS macros within the .~.MCALL format: 


-MCALL FCSMCS 
FCSMCS 


FCS macros declared in this manner include: OPENSx, 
OPNSSx, CLOSES, READS, WRITES, WAITS, GETS, PUTS, 
DELETS, FINITS, FSRSZS, FDBDFS, FDATSx, FDRCSx, 
FDOPSx, FDBFS$x, FDBKSx, and NMBLKS. If other macros 
are required, explicit .MCALL directives must be 
issued. One disadvantage of using this method to 
declare .MCALL directives is that unused macros may 
take up possibly critical assembler symbol table 
space, thus slowing down the assembly process. 


2.3 FILE DESCRIPTOR BLOCK (FDB) 


The File Descriptor Block (FDB) is the data structure that provides 
the information FCS needs for all file I/O operations. Two sets of 
macro calls are available for FDB initialization: you can use one set 
for assembly-time initialization (see Section 2.3.1) and the other set 
for run-time initialization (see Section 2.3.2). Use the run-time 
macros to supplement or override information specified during 
assembly. The FDB sections are described in Appendixes A and B. 


2.3.1 Assembly-Time FDB Initialization Macros 


Assembly-time initialization requires that the FDBDF$ macro call _ be 
issued (see Section 2.3.1.1) to allocate space for and to define the 
beginning address of the FDB. Additional macro calls can then be 
issued to establish other required information in this structure. 
The assembly-time macros that accomplish these functions are described 
in the following sections. 


Format 


mcnamSA pl,p2,...,pn 
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Macro Name 
mcnamSA 

The symbolic name of the macro. 
Parameter 


pl,p2,...,pn 


The string of initialization parameters associated with the 
specified macro. A parameter may be omitted from the string by 
leaving its field between delimiting commas null. Assume, for 
example, that a macro call may take the following parameters: 


FDOPSA 2,DSPT,DFNB 


Assume further that the second parameter field is to be coded as 
a null specification. In this case, the statement is coded as 
follows: 


FDOPSA 2,,DFNB 


A trailing comma need not be inserted to reflect the omission of 
a parameter beyond the last explicit specification. For example, 
the following macro call: 


FDOPSA 2,DSPT,DFNB 
need not be specified as 
FDOPSA 2,DSPT, 


if the last parameter (DFNB) is omitted. Rather, such a macro 
call is specified as follows: 


FDOPSA 2,DSPT 


If any parameter is not specified, that is, if any field in the macro 
call contains a null specification, the corresponding cell in the FDB 
is not initialized and thus remains 0. 


Multiple values may be specified in a parameter field of certain macro 
calls. Such values are indicated by placing an exclamation point (!) 
between the values, indicating a logical OR operation to the MACRO-11 
assembler. Specifying multiple values in this manner is mentioned 
throughout this manual if applicable to the macro call. 


Throughout the descriptions of the assembly-time macros in this 
section and elsewhere in this manual, symbols of the form F.xxx or 
F.xxxx are referenced (for example, F.RTYP). These symbols’ are 
defined as offsets from the beginning address of the FDB, allowing 
specific locations within the FDB to be referenced. Thus, you can 
reference or modify information within the FDB without having to 
calculate word or byte offsets to specific locations. 


Using such symbols in either system software or your software also 
permits the relative position of cells within the FDB to be changed 
(in a subsequent release, for example) without affecting your current 
programs or the coding style employed in developing new programs. 
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2.3.1.1 FDBDFS$ - Allocate File Descriptor Block (FDB) - The FDBDFS 
macro call is specified in a MACRO-11 program to allocate space within 
the program for an FDB. This macro call must be specified in the 
source program once for each input or output file that your program 
simultaneously opens during execution. Any associated assembly-time 
macro calls (see Sections 2.3.1.2 through 2.3.1.6) must then be 
specified immediately following the FDBDFS macro if you want to 
initialize certain portions of this FDB during assembly. 


Macro Name and Label 
label: FDBDFS 
label 


A symbol, which you specify, that names this particular FDB and 
defines its beginning address. This label is particularly 
significant in all I/O operations that require access to the data 
structure allocated through this macro call. FCS accesses the 
fields within the FDB relative to the address represented by this 
symbol. 


The following examples show how the FDBDFS macro calls might appear in 
your source program: 


FDBOUT: FDBDFS ;ALLOCATES SPACE FOR AN FDB NAMED 
;"FDBOUT" AND ESTABLISHES THE 
*;BEGINNING ADDRESS OF THE FDB. 


FDBIN: FDBDFS ;ALLOCATES SPACE FOR AN FDB NAMED 
;"FDBIN" AND ESTABLISHES THE 
;BEGINNING ADDRESS OF THE FDB. 


As noted earlier, the source program must embody one FDBDFS$ macro call 
logically similar to these example macro calls for your program to 
access each file simultaneously. FDBs can be reused for many 
different files, as long as the file currently using the FDB is closed 
before the next file is opened. The only requirement is that an FDB 
must be defined for every simultaneously opened file. 


2.3.1.2 FDATSA - Initialize File Attribute Section of FDB - The 
FDATSA macro call initializes the file attribute section of the FDB 
when a new output file is to be created. If the file to be processed 
already exists, the first four parameters of the FDATSA initialization 
macro need not be specified because FCS obtains the necessary 
information from the first 14 bytes of the file attribute section. 
The file attribute section is in the header block of the specified 
file. (See Appendix F.) 


Format 
FDATSA rtyp,ratt,rsiz,cntg,aloc 

Parameter 

rtyp 
A symbolic value that defines the type of records to be built as 
the new file is created. One of three values must be specified, 


as follows: 


® R.FIX - Indicates that fixed-length records are to be written 
in creating the file 


ratt 
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e R.VAR - Indicates that variable-length records are to be 
written in creating the file 


@ R.SEQ - Indicates variable-length sequenced records are to be 
written in creating the file 


The rtyp parameter initializes FDB offset location F.RTYP. 
Because symbols R.FIX, R.VAR, and R.SEQ initialize the same 
location in the FDB, these values are mutually exclusive. 


Symbolic values that may be specified to define the attributes of 
the records as the new file is created. 


The following parameters initialize the record attribute byte 
(offset location F.RATT) in the FDB. The values FD.FTN and FD.CR 
are mutually exclusive and must not be specified together. Apart 
from this restriction, the combination (logical OR) of multiple 
parameters specified in this field must be separated by an 
exclamation point (for example, FD.CR!FD.BLK). 


The following symbolic values may be specified, as appropriate, 
to define the desired record attributes: 


@e FD.FTN - Indicates that the first byte in each record will 
contain a FORTRAN carriage control character. 


e FD.CR - Indicates that the record is to be preceded by a <LF> 
character and followed by a <CR> character when the record is 
written to a carriage control device (for example, a line 
printer or a terminal). 


e FD.BLK - Indicates that records are not allowed to cross block 
boundaries. 


e FD.PRN - Indicates that the record is preceded by a word 
containing carriage control information; this value is the 
print file format attribute. Files that have this attribute 
set must also be sequenced files; that is, files that have the 
bit R.SEQ set in byte F.RTYP in the FDB. 


In a file with attribute FD.PRN, also known as COBOL carriage 
control, each record is associated with its own print format 
word, which describes the carriage control for that record, if 
the record is output to a unit record device such as a 
terminal or line printer. A program using FCS can read or 
write a file with attribute FD.PRN, but FCS ignores and does 
not interpret the format word if the file is written to a 
terminal. Thus, PIP correctly copies such a file from disk to 
disk, but a copy to TI: may not achieve the desired carriage 
control. 


FCS does not interpret the FD.PRN format word because such an 
enhancement would make FCS larger. Files with the FD.PRN 
attribute on RSX systems are rare. 


Files with the print file format attribute are a subset of 
sequenced files. Sequenced files are identified by record 
type R.SEQ in FDB field R.RTYP. Sequenced files have records 
of variable length; each record is associated with a l-word 
sequence number. (Note that sequential is not the same as 
sequenced. Sequential means that the file is not an RMS 
indexed or relative file. All sequenced files are also 
sequential.) 
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When a program is reading a sequenced file with FCS in record 
mode, FCS returns the record in the normal manner on a GETS; 
the sequence number is returned in FDB field F.SEQN. 
Conversely, when writing a sequenced file with FCS in record 
mode, FCS writes the record in the normal manner and writes 
the associated sequence number from F.SEQN. 


The sequence number field can contain any pattern of bits. A 


frequent application of this field is its use as a line number 
for text files. 


The difference between a file with attribute FD.PRN and any 
other sequenced file is that the sequence number is considered 
to be the carriage control format word. This word has a 
particular meaning in a file with attribute FD.PRN. Each byte 
of the format word describes the carriage control for the 
associated record. The low byte describes carriage control 
action that should occur before the record is printed; the 
high byte describes carriage control action that should occur 
after the record is printed. 


FCS operates on files with attribute FD.PRN in the same way 
that it operates on any other sequenced file, by using the FDB 
field F.SEQN for the format word. Each byte of the format 
word is defined as follows: 


Bits 0-6 Bit 7 Meaning 
0 0 No carriage control. 
1-127 0 Bits 0-6 are a count 
of line records. 
Bits 0-4 Bit 5 Bit 6 Bit 7 Meaning 
1-31. 0 0 1. Bits 0-4 define a 


7-bit ASCII control 
character to be 
output. 


1-31. 1 0 1 Bits 0-4 are 
translated as an 
8-bit ASCII control 
character ranging 
from 128. to 159. to 
be output. 


0 1 1 1 Reserved for future 
use. 


Because print format files must be sequenced files, FCS allows 
FD.PRN as an attribute of a new file only if record type R.SEQ 
is also specified. For example: 


FDBDFS$ ;Allocate space for FDB 
FDATSA ;Print file format 


FCS does not create a file with attribute FD.PRN that has a 
record type other than R.SEQ. In this case, FCS returns an 
error -45., IE.RAT, “illegal attribute bits set." 


rsiz 


cntg 


aloc 
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A numeric value that defines the size (in bytes) of fixed-length 
records to be written to the file. This value, which initializes 
FDB offset location F.RSIZ, need not be specified if R.VAR has 
been specified as the record type parameter (for variable-length 
records). If R.VAR or R.SEQ is specified, FCS maintains a value 
in FDB offset location F.RSIZ that defines the size (in bytes) of 
the largest record currently written to the file. Thus, whenever 
an existing file containing variable-length records is opened, 
the value in F.RSIZ defines the size of the largest record within 
that file. By examining the value in this cell, a program can 
dynamically allocate record buffers for its open files. 


A signed numeric value that defines the number of blocks that are 
allocated for the file as it is created. The signed values have 
the following significance: 


e Positive Value - Indicates that the specified number of blocks 
is to be allocated contiguously when the file is created; also 
indicates that the file is to be contiguous 


@ Negative Value - Indicates that the two's complement of the 
specified number of blocks is to be allocated when the file is 
created, not necessarily contiguously; also indicates that the 
file is to be noncontiguous 


The cntg parameter, which has 15 bits of magnitude (plus a= sign 
bit), initializes FDB offset location F.CNTG. 


(You can specify an allocation of up to 24 bits by using’ the 
-EXTND routine.) 


If you can estimate how long the file might be, it is more 
efficient to allocate the required number of blocks through this 
parameter when the file is created than to require FCS to extend 
the file when the file is written. (See the aloc parameter in 
the following text.) 


If this parameter is not specified, an empty file is created; 
that is, no space is allocated within the file as it is created. 


Issuing the CLOSES macro call at the completion of file 
processing resets the value in F.CNTG to 0. Thus, the usual 
procedure is to initialize this location at run time just before 
opening the file. Reinitialization is necessary if the FDB is 
reused. 


A signed numeric value that defines the number of blocks by which 
the file is extended, if FCS determines that file extension is 
necessary as records are written to the file. When the end of 
allocated space in the file is reached during writing, the signed 
value provided through this parameter causes file extension to 
occur, as follows: 


@e Positive Value - Indicates that the specified number of blocks 


is to be allocated contiguously as additional space within the 
file; also indicates that the file is to be contiguous. 
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@e Negative Value - Indicates that the two's complement of the 
specified number of blocks is to be allocated noncontiguously 
as additional space within the file; also indicates that the 
file is to be noncontiguous. 


NOTE 


Once a file has had blocks allocated, all future 
file extensions cause the file to become 
noncontiguous, even when aloc is a positive 
value. 


This parameter, which also has 15 bits of magnitude (plus a_ sign 
bit), initializes FDB offset location F.ALOC. If this optional 
parameter is not specified, file extension occurs as follows: 


e If the number of virtual blocks yet to be written is greater 
than 1, the file is extended by the exact number of blocks 
required to complete the writing of the file. 


@e If only one additional block is required to complete the 
writing of the file, the file is extended in accordance with 
the volume's default extend value. 


The volume default extend size is established through the INITIALIZE, 
INITVOLUME, or MOUNT command. The volume default extend size cannot 
be established at the FCS level; this value must be established when 
the volume is initially mounted. 


The following example statement shows a sample of an FDATSA macro 
call. This statement initializes the FDB in preparation for creating 
a new file containing fixed-length, 80-byte records that will be 
allowed to cross block boundaries. 


FDATSA R.FIX,,80. 


In the previous example statement, the record attribute (ratt) 
Parameter has been omitted, as indicated by the second comma (,) in 
the parameter string. Also, the cntg and aloc parameters have been 
omitted. Their omission, however, follows the last explicit 
specification, and their absence need not be indicated by trailing 
commas in the parameter string. Because the aloc parameter has been 
omitted, file extension (if it becomes necessary) is accomplished in 
accordance with the current default extend size in effect for the 
associated volume. 


If more than one record attribute is specified in the ratt parameter 
field, such specifications must be separated by an exclamation point 
(!), as shown in the macro following: 


FDATSA R.VAR,FD.FTN!FD.BLK 


The previous macro call enables a file of variable-length records’ to 
be created. The records will contain FORTRAN vertical-formatting 
information for carriage control devices; the records will not be 
allowed to cross block boundaries. 


PREPARING FOR 1/0 


2.3.1.3 FDRCSA - Initialize Record Access Section of FDB - The FDRCSA 
macro call initializes the record access section of the FDB, and 
indicates whether to use record or block I/O operations in processing 
the associated file. 


If you want to use record I/O operations (GETS and PUTS macro calls), 
the FDRCSA or the FDRCSR macro call (see Section 2.3.2) establishes 
the FDB information necessary for record-oriented I/0. However, if 
you want to use block I/O operations (READS and WRITES macro calls), 
the FDBKSA macro call (see Section 2.3.1.4) or the FDBKSR macro call 
(see Section 2.3.2) must also be specified to establish other values 
in the FDB required for block I/O. In this case, portions of the 
record access section of the FDB are physically overlaid with 
parameters from the FDBKSA/FDBKSR macro call. 


You must appropriately initialize the FDB to indicate whether record 
or block I/0 operations are to process the associated file, prior to 
issuing the OPENS macro call to initialize file operations. 


Format 

FDRCSA racc,urba,urbs 
Parameter 
racc 


Specifies which variation of block or record I/O is to process 
the file. This parameter initializes the record access byte 
(offset location F.RACC) in the FDB. The first value shown next, 
FD.RWM, applies only for block I/O (READS or WRITES) operations; 
all remaining values are specific to record I/O (GETS or PUTS) 
operations: 


e@ FD.RWM - Indicates that READS or WRITES (block I/0) operations 
are to process the file. If this value is not specified, GETS 
or PUTS (record I/0) operations process the file by default. 


Specifying FD.RWM necessitates issuing an FDBKSA or an FDBKSR 
macro call in the program to initialize other offsets in the 
block access section of the FDB. Note also that the READS or 
WRITES macro call allows the complete specification of all the 
parameters required for block I/O operations. 


e FD.RAN - Indicates that random access mode is to process’ the 
file. If this value is not specified, sequential access mode 
processes the file by default. See Section 1.5 for a 
description of random access mode. 


The following statement shows a sample FDRCSA macro call 
issued for a file that may be accessed in random mode: 


FDRCSA FD.RAN,BUF1,160. 


You specify the address of the task's record buffer through 
the symbol BUF1, and the size of the buffer (in bytes) by the 
numeric value 160(decimal). 


@e FD.PLC - Indicates that locate mode is to process the file. 
If this value is not specified, move mode processes the file. 


e FD.INS - Indicates that a PUTS operation performed within the 
body of the file shall not truncate the file. This value 
applies only for sequential files and therefore cannot be 
specified jointly with the FD.RAN parameter. 
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If you specify more than one value in the record access (racc) 
field, an exclamation point (!) must separate the multiple 
values, as shown here: 


FDRCSA FD.RAN!FD.PLC,BUF1,160. 


In addition to the functions described for the previous 
example, this example specifies that locate mode is to process 


the associated file. Note that the multiple parameters 
specified in the first field are separated by an exclamation 
point (!). 


If you want your task to perform a PUTS operation within the 
body of a file, the .POINT routine described in Section 4.10.1 
may be called. This routine positions the file to a byte you 
specify within a virtual block in preparation for the PUTS 
operation. The .POINT routine also permits a limited degree 
of random access to a file. 


If FD.INS is not specified, a PUTS operation within the file 
truncates the file at the point of insertion; that is, the 
PUTS operation moves the logical end-of-file (EOF) to a point 
just beyond the inserted record. However, no deallocation of 
blocks within the file occurs. 


Regardless of the setting of the FD.INS bit, a PUTS operation 
that is in fact beyond the current logical end-of-file resets 
the logical end of the file to a point just beyond the 
inserted record. 


urba 


The symbolic address of your task's record buffer used for GETS 
operations in move and locate modes, and for PUTS operations in 
locate mode. This parameter initializes FDB offset location 
F.URBD+2, and is specified only for record I/0 operations. 


urbs 


A numeric value that defines the size (in bytes) of your’ task's 
record buffer used for GETS operations in move and locate modes, 
and for PUTS operations in locate mode. This parameter 
initializes FDB offset location F.URBD, and is specified only for 
record I/O operations. 


You allocate and label a record buffer in a program by issuing a .BLKB 
or .BLKW directive. The address and the size of this area are then 
passed to FCS as the urba and the urbsS parameters shown previously. 
For example, a task's record buffer may be defined through a statement 
that is logically equivalent to: 


RECBUF: .BLKB 82. 


RECBUF is the address of the buffer and 82(decimal) is its size (in 
bytes). 


Beginning a task's record buffers on a word boundary can _ improve 
performance by allowing FCS to move the data with MOV instructions 
rather than MOVB instructions. 


Under certain conditions, you need not allocate a record buffer or 
specify the buffer descriptors (urba and urbs) for GETS or PUTS 
Operations. These conditions are described in detail in Sections 
3.9.2 and 3.12.2, respectively. 
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2.3.1.4 FDBKSA - Initialize Block Access Section of FDB - The FDBKSA 
macro call initializes the block access section of the FDB when block 
I/O operations (READS and WRITES macro calls) are used for file 
processing. Initializing the FDB with this macro call allows you to 
read or write virtual blocks of data within a file. 


Use of the FDBKSA macro call implies that the FDRCSA macro call has 
also been specified, because the FD.RWM parameter of the FDRCSA macro 
call initially declares block I/O operations. Thus, for block I/0 
operations, the FDRCSA macro call must be specified, as well as any 
one of the following macro calls, to appropriately initialize the 
block access section of the FDB: FDBKSA, FDBKSR, READS, or WRITES. 


Issuing the FDBKSA macro call causes certain portions of the record 
access section of the FDB to be overlaid with parameters necessary for 
block I/O operations. Thus, the terms "record access section" and 
"block access section" refer to a shared physical area of the FDB that 
is functional for either record or block I/O operations. 


The block I/O and record I/O FDB-initialization macros use the _ same 
area of the FDB for different data. Therefore, if record I/0 
operations are to be employed, neither the FDBKSA nor the FDBKSR macro 
call must be issued. 


Format 

FDBKSA bkda,bkds,bkvb,bkef,bkst,bkdn 
Parameter 
bkda 


The symbolic address of an area in your task's memory space to be 
employed as a buffer for block I/O operations. This parameter 
initializes FDB offset location F.BKDS+2. 


bkds 


A numeric value that specifies the size (in bytes) of the block 
to be read or written when a block I/O request (READS or WRITES 
macro call) is issued. This parameter initializes FDB offset 
location F.BKDS. The size specified must be an even, positive 
(the sign bit must not be set) value; the maximum number of bytes 
that can be specified is 32766. If an integral number of blocks 
is to be specified, the practical maximum number of bytes’ that 
can be specified is equal to 63 virtual blocks, or 32256 (decimal) 
bytes. 


bkvb 


A dummy parameter for compatibility with the FDBKSR macro call. 
The bkvb parameter is not specified in the FDBKSA macro call for 
the reasons stated in item 4 of Section 2.3.2.1. In short, 
assembly-time initialization of FDB offset locations F.BKVB+2 and 
F.BKVB with the virtual block number is meaningless, because any 
version of the generalized OPENSx macro call resets the virtual 
block number in these cells to 1 as the file is opened. 
Therefore, these cells can be initialized only at run time 
through either the FDBKSR macro call (see Section 2.2.2) or the 
I1/O-initiating READS and WRITES macro calls (see Sections 3.15 
and 3.16, respectively). 


bkef 


bkst 


bkdn 
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This dummy parameter should be reflected as a null specification 
(with a comma) in the parameter string only in the event that an 
explicit parameter follows. This null specification is required 
to maintain the proper position of any remaining field(s) in the 
Parameter string. 


A numeric value that specifies an event flag to be used during 
READS or WRITES operations to indicate the completion of a block 
I/O transfer. This parameter initializes FDB offset location 
F.BKEF; if not specified, event flag 32(decimal) is used by 
default. 


The function of an event flag is described in further detail in 
Section 2.9.1. 


The symbolic address of a 2-word I/0 status block in your 
program. If specified, this optional parameter initializes FDB 
offset location F.BKST. 


The I/O status block, if it is to be used, must be defined and 
appropriately labeled at assembly time. Then, if you specify the 
bkst parameter, information is returned by the system to the I1/0 
status block at the completion of the block I/O transfer. This 
information reflects the status of the requested operation. If 
this parameter is not specified, no information is returned to 
the I/O status block. 


NOTE 


If an error occurs during a READS or WRITES 
operation that would normally be reported as a 
negative value in the first byte of the I/0 
status block, the error is not reported unless 
you specify an I/O status block address. You are 
advised to specify this parameter, which allows 
the return of block I/O status information and 
permits normal error reporting. 


The creation and function of the I/O status block are described 
in detail in Section 2.9.2. 


The symbolic address of an optional AST service routine, which 
you code. If present, this parameter causes the AST service 
routine to be initiated at the specified address upon completion 
of block I/0; if not specified, no AST trap occurs. This 
parameter initializes FDB offset location F.BKDN. 


Considerations relevant to the use of an AST service routine are 
presented in Section 2.9.3. 


The following example shows an FDBKSA macro call that uses all 
available parameter fields for initializing the block access section 
of the FDB: 


FDBKSA BKBUF,240.,,20.,ISTAT,ASTADR 
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In this macro call, the symbol BKBUF identifies a block I/0 buffer 
reserved in your program that will accommodate a 240(decimal) -byte 
block. The virtual block number is null (for the reasons’ stated 
previously in the description of this parameter), and the event flag 
to be set upon block I/O completion is 20(decimal). Finally, the 
symbol ISTAT specifies the address of the I/O status block, and the 
symbol ASTADR specifies the entry point address of the AST service 
routine. 


2.3.1.5 FDOPSA - Initialize File-Open Section of FDB - The FDOPSA 
macro call initializes the file-open section of the FDB. In addition 
to a logical unit number, you would normally specify a dataset 
descriptor pointer and a default filename block address, or both, for 
each file that is to be opened. The latter two parameters provide FCS 
with the linkage necessary to retrieve file specifications from these 
data structures that you created in the program. 


Although both a dataset descriptor pointer (dspt) and the address of a 
default filename block (dfnb) may be specified for a given file, one 
or the other must be present in the FDB before that file can be 
opened. If, however, certain information is already present in the 
filename block as the result of prior program action, neither the 
dataset descriptor nor the default filename block is accessed by FCS, 
and the file is opened through a process called "opening a file by 
file ID." This process, which is an efficient method of opening a 
file, is described in detail in Section 2.6. 


The dspt and dfnb parameters represent address values that point to 
data structures that you created in the program. These data 
structures, which are described in detail in Section 2.5, provide file 
specifications to the FCS file-processing routines. 


Format 

FDOPSA lun,dspt,dfnb,facc,actl 
Parameter 
lun 


A numeric value that specifies a logical unit number. This 
parameter initializes FDB offset location F.LUN. All I/0 
operations performed with this FDB are done through the specified 
logical unit number (LUN). Every active FDB must have a unique 
LUN. 


The logical unit number specified through this parameter may be 
any value from 1 through the largest value specified to the Task 
Builder through the UNITS’ option. This option specifies the 
number of logical units that the task is to use (see the 
RSX-11M/M-Plus and Micro/RSX Task Builder Reference Manual. 


dspt 


The symbolic address of a 6-word block in your task containing 
the dataset descriptor. This data structure, which you created, 
consists of a 2-word device descriptor, a 2-word directory 
descriptor, and a 2-word file name descriptor, as outlined in 
Section 2.5.1. 


The dspt parameter initializes FDB offset location F.DSPT. This 
address value, called the dataset descriptor pointer, is the 
linkage address through which FCS accesses the fields in the 
dataset descriptor. 


dfnb 


facc 
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When the Command String Interpreter (CSI) processes command 
string input, a file specification is returned to the calling 
program in a format identical to that of the manually created 
dataset descriptor. The use of CSI as a dynamic command line 
processor is described in detail in Section 6.2. 


The symbolic address of the default filename block. This 
structure is allocated within your task through the NMBLKS macro 
call (see Section 2.4.2). When specified, the dfnb parameter 
initializes FDB offset location F.DFNB, allowing FCS to access 
the fields of the default filename block in building the filename 
block in the FDB. 


Specifying the dfnb parameter in the FDOPSA (or the FDOPSR) macro 
call assumes that the NMBLKS macro call has been issued in the 
program. Furthermore, the symbol specified as the dfnb parameter 
in the FDOPSA (or the FDOPSR) macro call must correspond exactly 
to the symbol specified in the label field of the NMBLKS macro 
call. 


Any one, or any appropriate combination, of the following 
symbolic values indicating how the specified file is to be 
accessed: 


e FO.RD - Indicates that an existing file is to be opened for 
reading only. 


e FO.WRT - Indicates that a new file is to be created and opened 
for writing. 


e FO.APD - Indicates that an existing file is to be opened for 
append. 


e FO.MFY - Indicates that an existing file is to be opened _ for 
modification. 


@e FO.UPD - Indicates that an existing file is to be opened for 
update and if necessary, extended. 


e FA.NSP - Indicates, in combination with FO.WRT, that an old 
file having the same file specification is not to be 
superseded by the new file. Rather, an error code is to be 
returned if a file of the same file name, type, and version 
exists. 


@e FA.TMP - Indicates, in combination with FO.WRT, that the 
created file is to be a temporary file. 


e FA.SHR - Indicates that the file is to be opened for shared 
access. Shared access is also a precondition for block 
locking. 


The facc parameter initializes FDB offset location F.FACC. The 
symbolic values FO.xxx, described previously, represent the 
logical OR of bits in FDB location F.FACC. 


The information specified by this parameter can be overridden by 
an OPENS macro call, as described in Section 3.7. It is 
overridden by an OPENSx macro call. 


actl 
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A symbolic value that specifies the following control information 
in FDB location F.ACTL: 


@e Magnetic tape position 


e Whether a disk file that is opened for write is to be locked 


if it is not properly closed; for example, the file may not be 
properly closed if the task terminates abnormally 


@ Number of retrieval pointers to allocate for a disk file 
window 


e Whether to enable block locking 


Normally, FCS supplies default values for F.ACTL. However, if 
FA.ENB is specified in combination with any of the symbolic 
values described in the following text, FCS uses the information 
in F.ACTL. FA.ENB must be specified with the desired values to 
override the defaults. The following are the defaults for 
location F.ACTL: 


e For file creation, magnetic tapes are positioned to the end of 
the volume set. 


e At file open and close, tapes are not rewound. 


e A disk file that is opened for write is locked if it is not 
properly closed. 


e The volume default is used for the file window. 
The following values can be used with FA.ENB: 


e FA.POS - Is meaningful only for output files and is specified 
to cause a magnetic tape to be positioned just after the most 
recently closed file for creating a new file. Any files that 
exist after that point are lost. If rewind is specified, it 
takes precedence over FA.POS, thus causing the tape to be 
positioned just after the VOL1 label for file creation. See 
Section 5.2.3 for more information on tape positioning. 


e FA.RWD - Is specified to cause a magnetic tape to be rewound 
when the file is opened or closed. 


Examples of using FA.ENB with FA.POS and FA.RWD are _ provided 
in Section 5.2.7. 


e FA.DLK - Is specified to cause a disk file not to be locked if 
it is not properly closed. 


The number of retrieval pointers for a file window can be 
specified in the low-order byte of F.ACTL. The default number 
of retrieval pointers is the file-window mapping pointer count 
parameter (/WIN) included in the INITIALIZE or MOUNT MCR 
commands; the default value for this parameter is 7. 
Retrieval pointers point to contiguous blocks of the file on 
disk. Access to fragmented files may be optimized by 
increasing the number of retrieval pointers, that is, by 
increasing the size of the window. Similarly, because 
retrieval pointers use up pool space, additional memory can be 
freed by reducing the number of pointers for files with little 
or no fragmentation, for example, contiguous files. 
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e FA.LKL!IFA.EXL - Is specified to lock all accessed blocks. FCS 
permits limited block locking to coordinate the access of the 
same file by two or more tasks. All tasks accessing the file 
must open the file for shared access by setting bit FA.SHR in 
FDB field F.FACC (the field access byte). 


See the RSX-11M/M-PLUS I/O Drivers Reference Manual or the 
Micro/RSX I/O Drivers Reference Manual for further information 
on block locking. Also, see Section 2.8.4 of this manual. 


As noted, if neither the dspt nor the dfnb parameter is specified, the 
corresponding offset locations F.DSPT and F.DFNB contain 0. In this 
case, no file is currently associated with this FDB. Any attempt to 
open a file with this FDB results in an open failure. Either offset 
location F.DSPT or F.DFNB must be initialized with an appropriate 
address value before a file can be opened using this FDB. Normally, 
these cells are initialized at assembly time through the FDOPSA macro 
call; but they may also be initialized at run time through the FDOPSR 
or the generalized OPENSx macro call (see Section 3.1). 


The following examples show how the FDOPSA macro call may be used in 
your source program: 


FDOPSA 1,,DFNB 


In this example that the dataset descriptor pointer parameter (dspt) 
is null, requiring that FCS rely on the run-time specification of the 
dataset descriptor pointer for the FDB or the use of the default 
filename block for required file information. 


FDOPSA 2,OFDSPT 


In this example, a dataset descriptor pointer (named OFDSPT) has been 
specified, allowing FCS to access the fields in the dataset descriptor 
for required file information. 


FDOPSA 2,OFDSPT,DFNB 


This example specifies both a dataset descriptor pointer and a default 
filename block address, causing FDB offset locations F.DSPT and 
F.DFNB, respectively, to be initialized with the appropriate values. 
In this case, FCS can access the dataset descriptor and the default 
filename block, or both, for required file information. By 
convention, FCS first seeks such information in the dataset 
descriptor; if all the required information is not present in this 
data structure, FCS attempts to obtain the missing information from 
the default filename block. 


FDOPSA 1,CSIBLK+C.DSDS 


This example shows a macro call that takes as its second parameter a 
symbolic value that causes FDB offset location F.DSPT to _ be 
initialized with the address of the CSI dataset descriptor. This 
structure is created in the CSI control block through invoking the 
CSI$ macro call. All considerations relevant to the use of CSI as a 
dynamic command line processor are presented in Section 6.2. 


FDOPSA 1,,DFNB,,FA.ENB!16. 


This example shows the use of the parameter actl to increase the 
number of retrieval pointers in the file window to 16. FA.ENB causes 
the contents of F.ACTL, rather than the defaults, to be used. 


In all the examples previously shown, the value specified as the first 
parameter supplies the logical unit number used for all I/O operations 
involving the associated file. 
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2.3.1.6 FDBFSA - Initialize Block Buffer Section of FDB - The FDBFSA 
macro call initializes the block buffer section of the FDB when record 
I/O operations (GETS and PUTS macro calls) process files. 
Initializing the FDB with this macro call allows FCS to control the 
necessary blocking and deblocking of individual records within a 
virtual block as an integral function of processing the file. 


Format 
FDBFSA efn,ovbs,mbct,mbfg 


efn 


A numeric value that specifies the event flag that FCS uses to 
synchronize record I/O operations. This numeric value 
initializes FDB offset location F.EFN. FCS uses this event flag 
internally; you must not set, clear, or test it. 


If this parameter is not specified, FCS uses’ event flag 
32(decimal). A null specification in this field is indicated by 
inserting a leading comma in the parameter string. 


ovbs 


A numeric value that specifies an FSR block buffer size, in 
bytes, that overrides the standard block size for the particular 
device associated with the file. This parameter initializes FDB 
offset location F.OVBS with the specified block buffer size. 


When you use ovbs to specify an FSR block buffer size for disks, 
specify the desired number of bytes in integral multiples of 512. 
bytes, overriding the one-sector, standard 512. bytes block 
buffer size. You can specify block buffer sizes up to 63 sectors 
(32256. bytes) for disks. Increasing the block buffer size in 
this manner greatly reduces average disk access time, because 
several contiguous sectors are generally read or written during a 
typical disk access operation. An override block size of 2048. 
bytes (4 sectors) or 2560. bytes (5 sectors) is recommended, 
because 2048. bytes also provides ANSI magnetic tape buffer 
capability, and 2560. bytes is the Files-1l default extend size. 
Note that once the file has been opened, FCS uses the ovbs field 
for other purposes. Thus, if your task uses the FDB_ for 
additional disk I/O operations, the ovbs parameter must be issued 
in an FDBFSR macro prior to accessing the disk. 


NOTE 


When you specify block buffer sizes greater than 
1 sector (S12. bytes), you must increase 
accordingly the size of SSFSR1l. This is done by 
specifying an appropriate value for the bufsiz 
parameter in the FSRSZS$ macro call (see Section 
227.1) 2 


Routines that read ANSI-standard magnetic tape without prior 
knowledge of the format of the files to be read must specify an 
override block size of 2048. bytes. This value is sufficient 
for the largest ANSI-standard tape blocks. 


mbct 


mbfg 
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Issuing the CLOSES macro call (see Section 3.8) resets offset 
location F.OVBS in the associated FDB to 0. Therefore, this 
location should typically be initialized at run time, just before 
opening the file, particularly if an OPENSx/CLOSES sequence for 
the file is performed more than once. 


On certain devices, such as line printers and terminals, the 
block size should not exceed the device's line width. The task 
can obtain the proper block size for these devices by issuing the 
Get LUN Information system directive for each device. (See the 
description for the Get LUN Information directive in the 
RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual.) The 
Standard block size for each device is established at system 
generation time, or by the MCR SET/BUF command. 


A numeric value that specifies the multiple buffer count, that 
is, the number of buffers FCS uses in processing the associated 
file. This parameter initializes FDB offset location F.MBCT. If 
this value is greater than 1, multiple buffering is effectively 
declared for file processing. In this case, FCS employs’ either 
read-ahead or write-behind operations, depending on which of two 
symbolic values is specified as the mbfg parameter (see the 
following entry). 


If the mbct parameter is specified as null or 0, FCS uses’ the 
default buffer count contained in symbolic location .MBFCT in 
SSFSR2 (the program section in the FSR containing impure data). 
This cell normally contains a default buffer count of l. If 
desired, this value can be modified, as noted in the discussion 
of the mbfg parameter in the following entry. 


If, in specifying the FSRSZ$ macro call (see Section 2.6.1), 
sufficient memory space has not been allocated to accommodate the 
number of buffers established by the mbct parameter, FCS 
allocates as many buffers as can fit in the available space. 
Insufficient space for at least one buffer causes FCS to return 
an error code to FDB offset location F.ERR. 


You can initialize the buffer count in F.MBCT through either the 
FDBFSA or the FDBFSR macro call. The buffer count so established 
is not altered by FCS and, once set, need not be of further 
concern to you. 


When input is from record devices (for example, a card reader), 
F.MBCT should not be greater than 2. 


A symbolic value that specifies the type of multiple buffering to 
be employed in processing the file. Either of two values may be 
specified to initialize FDB offset location F.MBFG: 


@ FD.RAH - Indicates that read-ahead operations are to be used 
in processing the file 


e FD.WBH - Indicates that write-behind operations are to be used 
in processing the file 


These parameters are mutually exclusive; that is, one or _ the 
other, but not both, may be specified. 
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Specifying this parameter assumes’ that the buffer count 
established in the mbct parameter shown previously is greater 
than 1. If multiple buffering has thus been declared, omitting 
the mbfg parameter causes FCS to use read-ahead operations by 
default for all files opened using the OPENSR macro call; 
Similarly, FCS uses write-behind operations by default for all 
files opened using other forms of the OPENSx macro call. 


If these default buffering conventions are not desired, you can 
alter the value in the F.MBFG dynamically at run time. This is 
done by issuing the FDBFSR macro call, which takes as the mbfg 
parameter the appropriate control flag (FD.RAH or FD.WBH). This 
action must be taken, however, before opening the file. 


Offset location F.MBFG in the FDB is reset to 0 each time the 
associated file is closed. 


NOTE 


When using write-behind multibuffering, there is 
no gain in efficiency if the size of the file 
must be increased to make room for the data to be 
written. If a file is being written at the end, 
using default extension, there will be one extend 
operation for each five write operations; thus, 
only 80% of the write-behind operations will 
actually be overlapped with processing. This 
percentage can be increased as follows: 


e Space for the file can be completely preallocated, either by 
using the cntg parameter in the FDATSA macro, or by using the 
-EXTND subroutine. 


e The default extension amount can be increased from five blocks 
by using the aloc parameter of the FDATSA macro call. For 
example, if an aloc parameter of 10(decimal) is specified, the 
number of write-behind operations that will be overlapped will 
increase to 90%. 


e The file can be accessed using random I/O. Because issuing 
PUTSR macros to access’ random preexisting locations in the 
file does not require extends, the percentage of overlapped 
operations is increased. 


You can change the default buffer count, if desired, by modifying a 
location in S$SFSR2, the second of two program sections comprising the 
FSR. A location defined as .MBFCT in SSFSR2 normally contains a 
default buffer count of 1. This default value may be changed, as 
follows: 


@ Apply a global patch to .MBFCT at task-build time to specify 
the desired number of buffers. 


@ For MACRO-11 programs, use the EXTSCT option of the Task 
Builder (see Section 2.7.1) to allocate more space for the FSR 
block buffers; for FORTRAN programs, use the ACTFIL option of 
the Task Builder (see Section 2.8.2) to allocate more space 
for the FSR block buffers. 
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Because the previous procedure alters the default buffer count for all 
files to be processed by your program, it may be desirable to force 
Single buffering for any specific file(s) that would not benefit from 
multiple buffering. In such a case, you can set the buffer count in 
F.MBCT for a specific file to 1 by issuing the following example macro 
call for the applicable FDB: 


FDBFSA ,,1 


The value 1 specifies the buffer count (mbct) for the desired file and 
is entered into offset location F.MBCT in the applicable FDB. Note in 
the previous example that the event flag (efn) and the override block 
buffer size (ovbs) parameters are null; these null values are for 
illustrative purposes only and _ should not be interpreted as 
conditional specifications for establishing single-buf fered 
operations. 


The following examples show how the FDBFSA macro call may be used in a 
program: 


FDBFSA 25.,,1 


This example specifies that event flag 25(decimal) synchronizes record 
I/O operations and that single buffering is used in processing the 
file. 


FDBFSA 25.,,2,FD.RAH 


This example also specifies event flag 25(decimal) for synchronizing 
record I/0 operations, and in addition establishes 2 as the multiple 
buffer count. The buffers so specified are for read-ahead operations, 
as indicated by the final parameter. 


FDBFSA 1,2,ED.WBH 


This example allows event flag 32(decimal) to be used by default for 
synchronizing record I/O operations, and the two buffers specified in 
this case are for write-behind operations. 


Note in all three examples that the second parameter, that is, the 
Override block size parameter (ovbs), is null; thus, the standard 
block size in effect for the device in question is used for all file 
I/O operations. 


2.3.2 Run-Time FDB Initialization Macros 


Although the FDB is allocated and can be initialized during program 
assembly, the contents of specific sections of the FDB can also be 
initialized or changed at run time by issuing any of the following 
macro calls: 


e FDATSR - Initializes or alters the file attribute section of 
the FDB. 


@ FDRCSR - Initializes or alters the record access section of 
the FDB. 


@® FDBKSR - Initializes or alters the block access section of the 
FDB (see item 4 in Section 2.2.1 following). 
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@ FDOPSR - Initializes or alters the file-open section of the 
FDB. 


e FDBFSR —- Initializes or alters the block buffer section of the 
FDB. 


There are no default values for run-time FDB macros (except for the 
FDB address). At run time, the values currently in the FDB are used 
unless they are explicitly overridden. For example, values stored in 
the FDB at assembly time are used at run time unless they are 
overridden. 


2.3.2.1 Run-Time FDB Macro Exceptions - The format and the parameters 
of the run-time FDB initialization macros are identical to the 
assembly-time macros described earlier, except as noted here: 


e An R rather than an A must appear as the last character in the 
run-time symbolic macro name. 


e The first parameter in all run-time macro calls must be the 
address of the FDB associated with the file to be processed. 
All other parameters in the run-time macro calls are identical 
to those described in Sections 2.2.1.2 through 2.2.1.6 for the 
assembly-time macro calls, except as noted in items 3 and 4 in 
this section. 


e The parameters in the run-time macro calls must be valid 
MACRO-11 source operand expressions. These parameters may be 
address values or literal values; they may also represent the 
contents of registers or memory locations. In short, any 
value that is a valid source operand in a MOV or MOVB 
instruction may be specified ina run-time macro call. In 
this regard, the following conventions apply: 


- If the parameter is an address value or a literal value 
that is to be placed in the FDB, that is, if the parameter 
itself is to be taken as an argument, it must be preceded 
by the number sign (#). This symbol is the immediate 
expression indicator for MACRO-1l programs, causing’ the 
associated argument to be taken literally in initializing 
the appropriate cell in the FDB. Such literal values’ may 
be specified as follows: 


FDOPSR' #FDBADR,#1,#DSPT, #DFNB 
- If the parameter is the address of a location containing an 
argument that is to be placed in the FDB, the parameter 
must be preceded by the number sign (#). Such a parameter 
may be specified as follows: 


ONE: -WORD 1 


FDOPSR #FDBADR, ONE, #+DSPT, #DFNB 


where ONE represents the symbolic address of a _ location 
containing the desired initializing value. 
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- But, if the parameter is a register specifier (for example, 
R4), the parameter must not be preceded by the number sign 
(#). Register specifiers are defined MACRO-11 symbols and 
are valid expressions in any context. 


NOTE 


RO can only be specified in the first parameter 
(FDB address). Any other use of RO will fail. 
(See Section 2.2.2.2, items 1 and 2.) 


Thus, in contrast, parameters specified in assembly-time macro 
calls are used as arguments in generating data in .WORD or 
-BYTE directives, while parameters specified in run-time macro 
calls are used aS arguments in MOV and MOVB- machine 
instructions. 


As noted in the description of the FDBKSA macro call in 
Section 2.3.1.4, assembly-time initialization of the FDB with 
the virtual block number is meaningless, because issuing the 
OPENSx macro call to prepare a file for processing resets the 
virtual block number in the FDB to l. For this reason, the 
virtual block number can be specified only at run time after 
the file has been opened. Do this by issuing either’ the 
FDBKS$R macro call or the I1/O-initiating READS or WRITES macro 
call. In all three cases, the relevant field for defining the 
virtual block number is the bkvb parameter. The READS and 
WRITES macro calls are described in detail in Sections 3.15 
and 3.16, respectively. 


At assembly time, you must reserve and label a 2-word block in 
the program to temporarily store the virtual block number 
appropriate for intended block I/0 operations. Because your 
task is free to manipulate the contents of these two locations 
at will, any virtual block number consistent with intended 
block I/0 operations may be defined. By specifying the 
symbolic address (that is, the label) of this field as the 
bkvb parameter in the selected run-time macro call, you can 
make the virtual block number available to FCS. 


In preparing for block I/O operations, you must follow’ these 
procedures: 


l. At assembly time, reserve a 2-word block in your program 
through a statement that is logically equivalent to the 
following: 


VBNADR: .BLKW 2 


The label VBNADR names this 2-word block and defines its 
address. This symbol is used subsequently as the bkvb 
parameter in the selected run-time macro call for 
initializing the FDB. 


2. At run time, load this field with the desired virtual 
block number. This operation may be accomplished through 
statements logically equivalent to those shown following: 


CLR VBNADR 
MOV #10400, VBNADR+2 
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Note that the first word of the block is cleared. The MOV 
instruction then loads the second (low-order) word of the 
block with a numeric value. This value constitutes the 16 
least significant bits of the virtual block number. 


If the desired virtual block number cannot be completely 
expressed within 16 bits, the remaining portion of the 
virtual block number must be stored in the first 
(high-order) word of the block. This may be accomplished 
through statements logically equivalent to the following: 


MOV #1,VBNADR 
MOV #10400, VBNADR+2 


As a result of these two instructions, 31 bits of value 
are defined in this 2-word block. The first word contains 
the 15 most significant bits of the virtual block number, 
and the second word contains the 16 least significant 
bits. Thus, the virtual block number is an unsigned value 
having 31 bits of magnitude. You must ensure that the 
sign bit in the high-order word is not set. 


3. Open the desired file for processing by issuing the 
appropriate version of the generalized OPENSx macro call 
(see Section 3.1). 


4. Issue either the FDBKSR macro call or the READS or WRITES 
macro call, as appropriate, to initialize the relevant FDB 
with the desired virtual block number. 


If the FDBKSR macro call is elected, the following is a 
representative example: 


FDBKSR #FDBIN,,,#VBNADR 


Regardless of the particular macro call that supplies the 
virtual block number, the two words at VBNADR are loaded 
into F.BKVB and F.BKVBt2. The first of these words 
(F.BKVB) is 0 if 16 bits are sufficient to express the 
desired virtual block number. The I/O-initiating READS or 
WRITES macro call may then be issued. 


Should you choose, however, to initialize the FDB directly 
through either the READS or WRITES macro call, the virtual 
block number may be made available to FCS through a 
statement such as that shown following: 


READS #FDBIN, #INBUF, #BUFSIZ,#VBNADR 


The symbol VBNADR represents the address of the 2-word 
block in your program containing the virtual block number. 


2.3.2.2 Specifying the FDB Address in Run-Time Macros - In 
relation to the second item of exceptions noted previously, the 
address of the FDB associated with the file to be processed 
corresponds to the address value of the symbol that you defined 
appearing in the label field of the FDBDF$ macro call (see Section 
2.3.1.1). For example, the following statement: 


FDBOUT: FDBDFS$ 
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not only allocates space for an FDB at assembly time, but also binds 
the label FDBOUT to the beginning address of the FDB associated with 
this file. The address value so established can then be specified as 
the initial parameter in a run-time macro call in any one of three 
ways: 


e The address of the appropriate FDB may be specified as an 
explicit parameter in a run-time macro call, as indicated in 
the following example statement: 


FDATSR #FDBOUT, #R. VAR, #FD.CR 


The argument FDBOUT is taken literally by FCS as the address 
of an FDB; furthermore, this address value, by convention, is 
stored in general register 0 (RO). Whenever this method of 
specifying the FDB address is employed, the previous contents 
of RO are overwritten (and thus destroyed). Therefore, you 
must exercise care in issuing subsequent run-time macro calls 
to ensure that the present value of RO is suitable to current 
purposes. 


@e You may use a general register specifier as the initial 
parameter in a run-time macro call. When you use a register 
other than RO, the contents of the specified register are 
moved to RO. The previous contents of RO are overwritten (and 
thus destroyed). 


The following statement reflects the use of a general register 
to specify the FDB address: 


FDATSR RO,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by FCS as 
the address of the appropriate FDB. This method assumes that 
the address of the FDB has been previously loaded into RO 
through some overt action. Note, when using this method to 
specify the FDB address, that the immediate expression 
indicator (#) must not precede the register specifier (RO). 


@e A null specification may be used as the initial parameter in a 
run-time macro call, as shown following: 


FDATSR ,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by default 
as the address of the associated FDB. As in method 2 shown 
previously, RO is assumed to contain the address of the 
desired FDB. Although the comma in this instance constitutes 
a valid specification, you are advised to employ methods 1 and 
2 for consistency and clarity of purpose. 


These three methods of specifying the FDB address also apply to all 
the FCS file-processing macro calls described in Chapter 3. 


2.4 GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS 


Although the FDB offsets can be defined either locally or globally, 
the design of FCS does not require that you be concerned with the 
definition of FDB offsets locally. To some extent, this design 
consideration is based on the manner in which MACRO-11 handles 
symbols. 
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Whenever a symbol appears in the source program, MACRO-11 assumes that 
it is a global symbol unless it is presently defined within the 
current assembly. Such a symbol must be defined further on in the 
program; otherwise, it will be treated by MACRO-11 as a default global 
reference, requiring that it be resolved by the Task Builder. 


Thus, the question of global versus local symbols may simply be a 
matter of the programmer's not defining the FDB offsets and bit values 
locally in coding the program. Such undefined symbols thus’ become 
global references, which are reduced to absolute definitions at 
task-build time. 


It should be noted that global symbols may be used as operands’ and 
macro-call parameters, or both, anywhere in the source program coding, 
as described in the following section. 


2.4.1 Specifying Global Symbols in the Source Code 


Throughout the descriptions of the assembly-time macros (see Sections 
2.3.1.2 through 2.3.1.6), global symbols are specified as parameters 
in the macro calls. As noted earlier, such symbols are treated by 
MACRO-11 as default global references. 


For example, the global symbol FD.RAN may be specified as the initial 
parameter in the FDRCSA macro call (see Section 2.3.1.3). At 
task-build time, this parameter is reduced to an absolute symbol 
definition, causing a prescribed bit to be set in the record access 
byte (offset location F.RACC) of the FDB. 


Global symbols may also be used as operands in your task's 
instructions to accomplish operations associated with FDB offset 
locations. For example, global offsets such as F.RACC, F.RSIZ, and 
F.RTYP may be specified as operands in the source coding. Assume, for 
example, that an FDBDFS$ macro call (see Section 2.3.1.1) has been 
issued in the source program to allocate space for an FDB, as follows: 


FDBIN: FDBDFS 


The coding sequence shown in the following text may then appear in the 
source program, illustrating the use of the global offset F.RACC: 


MOV #FDBIN, RO 
MOVB #FD.RAN,F.RACC (RO) 


Note that the beginning address of the FDB is first moved into general 
register zero (RO). However, if the desired value already exists in 
RO as the result of previous action in the program, you need issue 
only the second MOV instruction (which appropriately references RO). 
As a consequence of this instruction, the value FD.RAN initializes FDB 
offset location F.RACC. 


An equivalent instruction is the following: 
MOVB #FD.RAN, FOBIN+F.RACC 
which similarly initializes offset location F.RACC in the FDB with the 


value of FD.RAN. Global symbols may be used anywhere in the program 
in this manner to effect the dynamic storage of values within the FDB. 
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2.4.2 Defining FDB Offsets and Bit Values Locally 


If you want your task to declare explicitly that all FDB offsets and 
bit values are to be defined locally, there are two macro calls in the 
source program you can invoke. The first of these, FDOFSL, causes the 
offsets for FDBs to be defined within your program. Similarly, bit 
values for all FDB parameters may be defined locally by invoking the 
FCSBTS$ macro call. You can invoke these macro calls anywhere in your 
program. 


When issued, the FDOFSL and FCSBTS$ macro calls define symbols in a 
manner roughly equivalent to: 


F.RTYP = xxxx 
F.RACC = xxxx 
F.RSIZ = xxxx 


where xxxx represents the value assigned to the corresponding symbol. 


In other words, the macros for defining FDB offsets and bit values 
locally do not generate any code. Their function is simply to create 


absolute symbol definitions within the program at assembly time. The 
symbols so defined, however, appear in the MACRO-11 symbol table, 
rather than in the source program listing. Such local symbol 


definitions are thereby made available to MACRO-1l during assembly, 
rather than forcing them to be resolved by the Task Builder. 


Whether the FDOFSL and FCSBT$ macros are invoked should not in any way 
affect the coding style or the manner in which the FDB offsets and bit 
values are used. 


Note, however, that if the FDOFSL macro is issued, the NBOFSL macro 
for the local definition of the filename block need not be issued (see 
Section 2.5.2). The FDOFSL macro defines all FDB offsets locally, 
including those for the filename block. 


If any of the previously named macros is to be issued in your program, 


it must first be listed as an argument in an .MCALL directive (see 
Section 2.2). 


2.5 CREATING FILE SPECIFICATIONS WITHIN YOUR PROGRAM 

Certain information describing the file must be present in the FDB 
before the file can be opened. The file is located using a file 
specification that contains the following: 

1. A device name and unit number. 

2. A directory string consisting of a group number and a member 
number that specify the User File Directory (UFD) to be used 
for the file. The term "UFD" is synonymous with the term 
"file directory string" appearing throughout this manual. 

3. A file name. 

4. A file type. 


5. A file version number. 


PREPARING FOR I/0 


A file specification describing the file to be processed is 
communicated to FCS through two data structures that you create: 


l. The dataset descriptor. This tabular structure may be 
created and initialized manually through the use of .WORD 
directives. Section 2.4.1 describes this data structure in 
detail. 


2. The default filename block. In contrast to the manually 
created dataset descriptor, the default filename block is 
created by issuing the NMBLKS macro call. This macro call 
allocates a block of storage in your program at assembly time 
and initializes this structure with parameters supplied in 
the call. This structure is described in detail in Section 
2.4.2. 


As noted in Section 2.3.1.5, the FDOPSA or the FDOPSR macro call is 
issued to initialize the FDB with the addresses of these data 
structures. These address values are supplied to FCS through the dspt 
and dfnb parameters of the selected macro call. FCS uses these 
addresses to access the fields of the dataset descriptor and _ the 
default filename block, or both, for the file specification required 
in opening a specified file. 


By convention, a required file specification is first sought by FCS in 
the dataset descriptor. Any nonnull data contained therein is 
translated from ASCII to Radix-50 form and stored in the appropriate 
offsets of the filename block. This area of the FDB then serves as 
the execution time repository for the information describing the file 
to be opened and processed. If the dataset descriptor does not 
contain the required information, FCS attempts to obtain the missing 
information from the default filename block. If neither of these 
structures contains the required information, an open failure occurs. 


Note, however, that the device name and the unit number need not be 
specified in either the dataset descriptor or the default filename 
block, because these values are defaulted to the device and unit 
assigned to the LUN at task-build time if not explicitly specified. 


The FCS file-processing macro calls used in opening files are 
described in Chapter 3, beginning with the generalized OPENSx macro 
call in Section 3.1. 


For a detailed description of the format and content of the filename 
block, refer to Appendix B. 


2.5.1 Dataset Descriptor 


The dataset descriptor is often oriented toward the use of a fixed 
(built-in) file name in your program. A given application program, 
for example, may require access only to a limited and nonvariable 
number of files throughout its execution. By defining the names of 
these files at assembly time through the dataset descriptor mechanism, 
such a program, once initiated, executes to completion without 
requiring additional file specifications. 


This structure, a 6-word block of storage that you can create manually 
within your program by using .WORD directives, contains information 
describing a file that you intend to open during the course of program 


execution. 


of three 
follows: 
e hU6U<€A 


This data 
format: 
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In creating this structure, you can define any one or all 


possible 


string descriptors for a particular file, as 


2-word descriptor for an ASCII device name string 


2-word descriptor for an ASCII file directory string 


2-word descriptor for an ASCII filename string 


structure is allocated in your program in the following 


DEVICENAME STRING DESCRIPTOR 


Word l - 


Word 2 - 


Contains the length (in bytes) of the ASCII device 
name string. 


This string consists of a 2-character alphabetic 
device name, followed by an optional octal unit 
number and an optional colon. You can create 
these strings by issuing statements such as these: 
DEVNM: .ASCII /DKO:/ 
DEVNM: .ASCII /TT10:/ 


Contains the address of the ASCII device name 
String. 


DIRECTORY STRING DESCRIPTOR 


Word 3 =- 


Word 4 - 


Contains the length (in bytes) of the ASCII file 
directory string. 


This string consists of a group number and a 
member number, separated by a comma (,). The 
entire string is enclosed in brackets. For 
example, [200,200] is a directory string. You can 
create a directory string by issuing statements 
such as these: 


DIRNM: .ASCII /[200,200]/ 
DIRNM: .ASCII /[40,100]/ 


If you want your task to specify an explicit file 
directory different from the UIC under which you 
are currently running, the dataset descriptor 
mechanism permits that flexibility. 


Contains the address of the ASCII file directory 
string. 


FILENAME STRING DESCRIPTOR 


Word 5 - 


Contains the length (in bytes) of the ASCII 
filename string. 


This string consists of a file name up to 9 
characters in length, an optional 3-character file 
type designator, and an optional file version 
number. The file name and file type must be 
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separated by a period (.), and the file version 
number must be preceded by a_ semicolon. A 
filename string may be created as shown following: 


FILNM: .ASCII /PROG1.OBJ;7/ 


For Files-1l, only the characters A through Z and 
0 through 9 may be used in composing an ASCII 
filename string. An ANSI magnetic tape filename 
string may contain, in addition, the following 
special characters: 


SP ! " $& " () * +,--264 /3 3€ =>? 


A name that contains any of these characters must 
be enclosed in quotation marks. If a quotation 
mark is part of the name, the string must contain 
two quotation marks. An ANSI filename string may 
be created as shown in the next example: 


FILNM: .ASCII /"PROG"™"2"":%&,"27/ 
The file name created in the previous example is: 


PROG"2"3 %&;3 7 


NOTE 


The semicolon is a legal character in the 
name string. To delimit a version number, 
the semicolon must be outside the quoted 
string. 


Word 6 - Contains the address of the ASCII filename string. 


A length specification of 0 in Word 1, 3, or 5 of the dataset 
descriptor indicates that the corresponding device name, directory, or 
filename string is not present in your. program. For example, the 
following code creates a dataset descriptor containing only a 2-word 
ASCII filename string descriptor: 


FDBOUT: FDBDFS$ ,;CREATES FDB. 
FDATSA R.VAR,FD.CR ; INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA_ ,RECBUF,80. ; INITIALIZES RECORD-ACCESS SECTION. 
FDOPSA OUTLUN,OFDSPT ;INITIALIZES FILE-OPEN SECTION. 


OFDSPT: .WORD 0,0 ;NULL DEVICE-NAME DESCRIPTOR. 
-WORD 0,0 ;NULL DIRECTORY DESCRIPTOR. 
-WORD ONAMSZ , ONAM ;FILENAME DESCRIPTOR. 


ONAM: -ASCII /OUTPUT.DAT/ ;DEFINES FILENAME STRING. 
ONAMSZ=. —-ONAM ;DEFINES LENGTH OF FILENAME STRING. 


° 
° 
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Note first that an FDB labeled FDBOUT is’ created. Observe further 
that the FDOPSA macro call takes as its second parameter the symbol 
OFDSPT. This symbol represents the address value stored in FDB offset 
location F.DSPT. This value enables the .PARSE routine (see Section 
4.7.2) to access the fields of the dataset descriptor in building the 
filename block. 


The symbol OFDSPT also appears in the label field of the first .WORD 
directive, defining the address of the dataset descriptor for the 
-PARSE routine. The .WORD directives each allocate two words of 
storage for the device name descriptor, the file directory descriptor, 
and the filename descriptor, respectively. 


In the example above, however, note that the first two descriptor 
fields are filled with zeros, indicating null specifications. The 
last .WORD directive allocates two words that contain the size and the 
address of the filename string, respectively. The filename string 
itself is explicitly defined in the .ASCII directive that follows. 


Note that the statements defining the filename string need not be 
physically contiguous to the dataset descriptor. For each such ASCII 
string referenced in the dataset descriptor, however, corresponding 
Statements must appear elsewhere in the source program to define the 
appropriate ASCII data string(s). 


A dataset descriptor for each of several files to be accessed by your 
program may be defined in this manner. 


2.5.2 Default Filename Block -— NMBLKS Macro 


As noted earlier, you may also define a default filename block in the 
program as a means of providing required file information to FCS. For 
this purpose, you can issue the NMBLKS$ macro call in connection with 
each FDB for which a default filename block is to be defined. When 
this macro call is issued, space is allocated within your program for 
the default filename block, and the appropriate locations within this 
data ae ahaa are initialized according to the parameters supplied in 
the call. 


Note in the parameter descriptions in the following text that symbols 
of the form N.xxxx are used to represent the offset locations within 
the filename block. These symbols are differentiated from those that 
apply to the other sections of the FDB by the beginning character N. 
All versions of the generalized OPENSx macro call (see Section 3.1) 
use these symbols to identify offsets in storing file information in 
the filename block. 


Format 

label: NMBLKS fnam,ftyp,fver,dvnm,unit 
Parameter 
label 


A symbol, which you define, that names the default filename block 
and defines its address. This label is the symbolic value 
normally specified as the dfnb parameter when the FDOPSA or _ the 
FDOPSR macro call is issued. This causes FDB offset location 
F.DFNB to be initialized with the address of the default filename 
block. 
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fnam 


The default file name. This parameter may consist of up to nine 
ASCII characters. The character string is stored as six bytes in 
Radix-50 format, starting at offset location N.FNAM of the 
default filename block. 


ftyp 


The default file type. This parameter may consist of up to three 
ASCII characters. The character string is stored as two bytes in 
Radix-50 format in offset location N.FTYP of the default filename 
block. 


fver 


The default file version number (binary). When specified, this 
binary value identifies a particular version of a file. This 
value is stored in offset location N.FVER of the default filename 
block. 


dvnm 


The default name of the device upon which the volume containing 
the desired file is mounted. This parameter consists of two 
ASCII characters that are stored in offset location N.DVNM of the 
default filename block. 


unit 


A binary value identifying which unit (among several like units) 
is to be used in processing the file. If specified, this numeric 
value is stored in offset location N.UNIT of the default filename 
block. 


Only the alphanumeric characters A through Z and 0 through 9 may _ be 
used in composing the filename and filetype strings discussed 
previously. Although the file version number and the unit number 
discussed previously are binary values, these numbers are normally 
represented in octal form when printed, when input by a command 
string, or when supplied through a dataset descriptor string. 


As evident from the foregoing, all the default information supplied in 
the NMBLKS macro call is stored in the default filename block at 
offset locations that correspond to identical fields in the filename 
block within the FDB. This default information is moved into the 
corresponding offsets of the filename block when any version of the 
generalized OPENSx macro call is issued under any of the following 
conditions: 


e All the file information required by FCS to open the file is 
not present in the dataset descriptor. Missing information is 
then sought in the default filename block by the’ .PARSE 
routine (see Section 4.7.2), which is invoked as a result of 
issuing any version of the generalized OPENSx macro call. 


e A dataset descriptor has not been created in your program. 


e A dataset descriptor is present in your program, but’ the 
address of this structure has not been made available to FCS 
through any of the assembly-time or run-time macro calls that 
initialize FDB offset location F.DSPT. 
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The following code illustrates the general method of specifying the 
NMBLKS macro call: 


FDBOUT: FDBDFS ;ALLOCATES SPACE FOR AN FDB. 
FDATSA R.VAR,FD.CR ; INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA_ ,RECBUF, 80. ; INITIALIZES RECORD-ACCESS SECTION. 
FDOPSA OUTLUN, ,OFNAM ; INITIALIZES FILE-OPEN SECTION. 

FDBIN: FDBDFS ;ALLOCATES SPACE FOR AN FDB. 
FDRCSA_ ,RECBUF,80. ; INITIALIZES RECORD-ATTRIBUTE SECTION. 
FDOPSA INLUN,,IFNAM ; INITIALIZES FILE-OPEN SECTION. 

OFNAM: NMBLKS OUTPUT,DAT ;ESTABLISHES FILE NAME AND FILE TYPE. 


IFNAM: NMBLKS INPUT,DAT,,DT,1 ;ESTABLISHES FILE NAME, FILE TYPE, 
;DEVICE NAME, AND UNIT NUMBER. 


The first NMBLKS$ macro call in the previous coding sequence creates a 
default filename block to establish default information for the FDB, 
named FDBOUT. The label OFNAM in this macro defines the beginning 
address of the default filename block allocated within your program. 
Note that this symbol is specified as the dfnb parameter in the FDOPSA 
macro call associated with this default filename block to initialize 
the file open section of the corresponding FDB. The accompanying 
parameters in the first NMBLKS$ macro call define the file name and the 
file type, respectively, of the file to be opened; all remaining 
Parameter fields in this call are null. 


The second NMBLKS$ macro call accomplishes essentially the same 
operations in connection with the FDB, named FDBIN. Note in this 
macro call that the third parameter (the file version number) is null, 
as reflected by the extra comma. This null specification indicates 
that the latest version of the file is desired. All other parameter 
fields contain explicit declarations defining default information for 
the applicable FDB. 


You can define the offsets for a filename block locally in your 
program by issuing the following macro call: 


NBOFSL 


This macro call does not generate any code. Its function is merely to 
define the filename block offsets locally, presumably to conserve 
symbol table space at task-build time. The NBOFSL macro call need not 
be issued if the FDOFSL macro call has been invoked, because the 
filename block offsets are defined locally as a result of issuing the 
FDOFSL macro call. 


If you want, you may initialize fields in the default filename block 
directly with appropriate values. You can do this by placing in-line 
statements in the program. For example, a specific offset in the 
default filename block may be initialized through coding that is 
logically equivalent to the following: 


DFNB: NMBLKS$S RSXLIB,OBJ 


NUTYP: .RAD50 /DAT/ 


MOV NUTYP, DFNB+N.FTYP 
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where the symbol NUTYP in the MOV instruction represents the address 
of the newly defined Radix-50 file type DAT, which is to be moved into 
destination offset N.FTYP of the default filename block labeled DFNB. 
You can manually initialize any of the offsets within the default 
filename block in this manner to establish desired values or _ to 
Override previously initialized values. 


NOTE 


The NMBLKS macro cannot be used to create a file name 
containing non-Radix-50 characters or a file name that 
is not in the normal filenam.typ format. A program 
that uses the file name format permitted for ANSI 
magnetic tape must set up the file name in a dataset 
descriptor. 


2.5.3 Dynamic Processing of File Specifications 


If you want your task to make use of routines available from _ the 
System object library ({1,1]SYSLIB.OLB) for processing command line 
input dynamically, consult Chapter 6. Chapter 6 describes the Get 
Command Line (GCML) routine and the Command String Interpreter (CSI) 
routine, both of which may be linked with your program to provide all 
the logical capabilities required in processing dynamic terminal input 
or indirect command file input. 


2.6 OPTIMIZING FILE ACCESS 


When certain information is present in the filename block beginning at 
the symbolic F.FNB of an FDB, a file can be opened in a manner 
referred to throughout this manual as "opening a file by file ID." 
This type of open requires a minimum of system overhead, resulting in 
a Significant increase in the speed of preparing a file for access by 
your program. If files are frequently opened and closed during 
program execution, opening files by file ID accomplishes’ substantial 
savings in overall execution time. 


To open a file by file ID, the minimum information that must be 
present in the filename block of the associated FDB consists of the 
following: 


e File Identification Field. This 3-word field, beginning at 
filename block offset location N.FID, contains a file number 
in the first word and a file sequence number in the’ second 
word; the third word is reserved. The file identification 
field is maintained by the system and ordinarily need not be 
of concern to you. 


@ Device Name Field. This l-word field at filename block offset 
location N.DVNM contains the 2-character ASCII name of the 
device on which the volume containing the desired file is 
mounted. 


e Unit Number Field. This l-word field at filename block offset 
location N.UNIT contains a binary value identifying the 
particular unit (among several like units) on which the volume 
containing the desired file is mounted. 
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These three fields are written into the filename block in one of three 
ways: 


e By issuing any version of the generalized OPENSx macro call 
for a file associated with the FDB in question. 


e By initializing the filename block manually by using’ the 
-PARSE routine (see Section 4.7.1) and the .FIND routine (see 
Section 4.8.1). 


e By moving the necessary values into the filename block. 


Opening an existing file by file ID is a special case (see Section 
33 5) 


2.6.1 Initializing the Filename Block as a Function of OPENSx 


To understand how to effect the process of opening a file by file ID, 
note that the initial issuance of the generalized OPENS$x macro call 
(see Section 3.1) for a given file first invokes the .PARSE routine 
(see Section 4.7.2). The .PARSE routine is linked into your program, 
along with the code for OPENSx. This routine first zeros the filename 
block and then fills it in with information taken from the dataset 
descriptor and the default filename block, or both. 


Thus, issuing the generalized OPENSx macro call invokes the .PARSE 
routine each time a file is opened. The .PARSE function, however, can 
be bypassed altogether in subsequent OPENSx calls by saving and 
restoring the filename block before attempting to reopen that same 
file. 


This is made possible because of the logic of the OPENSx macro call. 
Specifically, after the initial OPENSx for a file has been completed, 
the necessary context for reopening that file exists within the 
filename block. Therefore, before closing that file, the entire 
filename block can be copied into your task's memory space and later 
restored to the FDB at the desired point in program flow for use in 
reopening that same file. 


Your task can reopen files in this manner because FCS is sensitive to 
the presence of any nonzero value in the first word of the file 
identification field of the filename block. When your task invokes 
the OPENSx function, FCS first examines offset location N.FID of the 
filename block. If the first word of this field contains a value 
other than 0, FCS logically assumes that the remaining context 
necessary for opening that file is present in the filename block, and 
therefore unconditionally opens that file by file ID. 


To ensure that an undesired value does not remain in the first word of 
the N.FID field from a previous OPENSx or CLOSES sequence, the first 
word of this field is zeroed as the file is closed. 


In opening files by file ID, you need only ensure that manual saving 
and restoring of the filename block are accomplished with in-line MOV 
instructions that are consistent with the desired sequence of 
processing files. This process should proceed as follows: 


1. Open the file in the usual manner by issuing the OPENSx macro 
call. 


2. Save the filename block by copying it into your task's memory 
Space with appropriate MOV instructions. The filename block 
begins at offset location F.FNB in the file descriptor block 
(FDB). 
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The value of the symbol S.FNB is the size of the filename 
block in bytes, and the value of the symbol S.FNBW is the 
size of the filename block in words. If desired, the NBOFSL 
Macro call (see Section 2.5.2) may be invoked in your program 
to define these symbols locally. These symbolic values may 
be used in appropriate MOV instructions to accomplish the 
saving and restoring of the filename block. Moreover, you 
must reserve sufficient space in the program for saving the 
filename block. 


3. At the end of current file operations, close the file in the 
usual manner by issuing the CLOSES macro call. 


4. When, in the normal flow of program logic, that same file is 
about to be reopened, restore the filename block to the FDB 
by reversing step 2. 


5. Reopen the file by issuing any one of the macro calls 
available in FCS for opening an existing file. Because the 
first word of offset location N.FID of the filename block now 
contains a nonzero value, FCS unconditionally opens the file 
by file ID, regardless of the specific type of open macro 
call issued. 


Although you must save only the file identification, device name, and 
unit number fields of the filename block in anticipation of reopening 
a file by file ID, you are advised to save the entire filename block. 
The file name, file type, file version, and directory-ID fields, and 
so forth, may also be relevant. For example, an OPENSx, save, CLOSES, 
restore, OPENSx, and DELET$ sequence would require saving and 
restoring the entire filename block. 


Though you may be logically finished with file processing and may want 
to delete the file, the delete operation will not work properly unless 
the entire filename block has been saved and restored. 


2.6.2 Manually Initializing the Filename Block 


In addition to saving and restoring the filename block in anticipation 
of reopening a file by file ID, you can also initialize the filename 
block manually. If you choose to do so, the .PARSE and .FIND routines 
(see Sections 4.7.2 and 4.8.1, respectively) may be invoked at 
appropriate points to build the required fields of the filename block. 
After the .PARSE and _ .FIND logic is completed, all the information 
required for opening the file exists within the filename block. When 
any one of the available FCS macro calls that open existing files is 
then issued, FCS unconditionally opens that file by file ID. 


Occasionally, instances arise that make such manual operations 
desirable, especially if your program is operating in an overlaid 
environment. In this case, it is highly desirable that the code for 
opening a file be broken into small segments in the interest of 
conserving memory space. Because the body of code for the OPENSx and 
-PARSE functions is sizable, two other types of macro calls for 
opening files are provided for use with overlaid programs. The OFIDS 
and OFNBS macro calls (see Sections 3.5 and 3.6, respectively) are 
specifically designed for this purpose. 


The structure recommended for an overlaid environment is to have 
either the OFIDS or the OFNBS code on one branch of the overlay and 
the .PARSE and .FIND code on another branch. Then, if you want your 
task to open a file by file ID, the .PARSE and .FIND routines can be 
invoked at will to insert required information in the filename _ block 
before opening the file. 
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The OFIDS$ macro call can be issued only in connection with an existing 
file. The OFNBS macro call, on the other hand, may be used for 
opening either an existing file or for creating and opening a new 
file. In addition, the OFNBS macro call requires only the manual 
invocation of the .PARSE routine to build the filename block before 
opening the file. 


If conservation of memory is an objective, and if your program will be 
opening both new and existing files, it is recommended that only the 
OFNBS routine be included in one branch of the overlay; including the 
OFIDS routine would needlessly consume memory space. 


In all cases, however, it is important to note that all the macro 
calls for opening existing files are sensitive to the presence of any 
nonzero value in the first word (N.FID) of the filename block. Tf 
this field contains any value other than 0, the file is 
unconditionally opened by file ID. This does not imply, however, that 
only the file identification field (N.FID) is required to open the 
file in this manner. The device name field (N.DVNM) and the unit 
number field (N.UNIT) must also be appropriately initialized. The 
logic of the FCS macro calls for opening existing files assumes’ that 
these other required fields are present in the filename block if the 
file identification field contains a nonzero value. 


Because many programs continually reuse FDBs, the CLOSES function (see 
Section 3.8) puts zeros in the file identification field (N.FID) of 
the filename block. This action prevents the field (which pertains to 
a previous operation) from being used mistakenly to open a file for a 
current operation. Thus, if your task later intends to open a file by 
file ID using information presently in the filename block, the entire 
filename block (not just N.FID) must be saved before closing the file. 
Then, at the appropriate point in program flow, the filename block may 
be restored to open the desired file by file ID. 


2.7 INITIALIZING THE FILE STORAGE REGION 


The file storage region (FSR) is an area allocated in your program as 
a buffer pool to accommodate the program's block buffer requirements 
in performing record I/O (GETS and PUTS) operations. Although the FSR 
is not applicable to block I/O (READS and WRITES) operations, you must 
issue the FSRSZS$ macro once in every program that uses FCS, regardless 
of the type of I/0 to be performed. 


The macro calls associated with the initialization of the FSR are 
described next. 


2.7.1 FSRSZ$ - Initialize FSR at Assembly Time 


The MACRO-11 programmer establishes the size of the FSR at assembly 
time by issuing an FSRSZ$ macro call. This macro call does not 
generate any executable code. It merely allocates space for a 
block-buffer pool in a program section named SSFSR1. The amount of 
Space allocated depends on information provided by you, or defaulted, 
during the macro call. 


Forma 


t 
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NOTE 


The FSRSZS macro allocates the FCS impure area that is 
pointed to by a fixed location in your task's virtual 
memory. This pointer is not altered when overlays are 
loaded; therefore, the FSRSZS macro must be invoked in 
the root segment of a task. Unpredictable results may 
occur if the FSRSZS$ macro is invoked in more than one 
parallel overlay. 


FSRSZ$ fbufs,bufsiz,psect 


Parameter 


fbufs 


A numeric value that you establish as follows: 


If no record I/O processing is to be done, fbufs equals 0. A 
value of 0 indicates that an unspecified number of files may 
be open simultaneously for block I/O processing. For example, 
if you intend to access three files for block I/O operations 
and no files for record I/O operations, the FSRSZ$ macro call 
takes 0 as an argument: 


FSRSZS 0 


No other parameters need be specified unless the function of 
the psect parameter is required. 


If record I/O, using a single buffer for each file, is to be 
done, fbufs represents the maximum number of files that can be 
open simultaneously for record I/O processing. For example, | 
you might want to access simultaneously three files for block 
I/O and two files for record I/0. You would specify the 
following FSRSZS$ macro call: 


FSRSZS 2 


Additional parameters, bufsiz and psect (described 
subsequently) could also be specified as required. 


If record I/O with multiple buffering is to be done, fbufs 


represents the maximum number of buffers ever in use 
simultaneously among all files open concurrently for record 
Ifo. Assume, for example, that your program will 
simultaneously access four disk files for record I/O 


operations. Assume further that you want double-buffering for 
three of the disk files and have, therefore, specified a 
multiple buffer count of 2 in the FDBFSA macro calls (refer to 
Section 2.3.1.6) for the associated files. You would then 
issue the following FSRSZS$ macro call: 


FSRSZ$ 7 


This macro call indicates that a maximum of seven buffers will 
be in use simultaneously. This total is calculated as 
follows: one buffer for the single-buffered file and two 
buffers for each of the three double-buffered files. 
Additional parameters, bufsiz and psect (described next), 
could also be specified as required. 
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bufsiz 


psect 


A numeric value defining the total block buffer pool space (in 
bytes) needed to support the maximum number of files that can be 
open simultaneously for record I/O. If this parameter is 
omitted, FCS obtains a total block buffer pool requirement by 
multiplying the value specified in the fbufs parameter with a 
default buffer size of 512 bytes. If, for example, a maximum of 
two single-buffered disk files will be open simultaneously for 
record I/0, either of the following FSRSZS$ macro calls could be 
issued: 


FSRSZS 2 
FSRSZS 2,1024. 


If you want your task to explicitly specify block buffer pool 
requirements, the following formula must be applied: 


bufsiz=(bsizel*mbcl) [+ (bsize2*mbc2) ...+(bsizen*mbcn) } 
bsizel,bsize2,...,bsizen 


The sizes, in bytes, of the buffers to support each file. 
The size of a buffer for a particular file depends on the 
device supporting the file if the standard block buffer size 
is used. Standard block sizes for devices are established 
at system generation time. The override block buffer size 
(ovbs) parameter can be used in the FDBFSx macro call to 
increase buffer size, as described in Section 2.2.1.6; these 
increases must be considered when you explicitly specify 
block buffer pool requirements. 


mbcl,mbc2,...,mbcn 


The multiple buffer counts (refer to Section 2.3.1.6) 
specified for the respective files. 


The total value expressed by the bufsiz parameters must 
always represent the worst case buffer pool requirements 
among all combinations of simultaneously open record I/0 


files. The number of files (or buffers) representing the 
worst case is expressed as the first parameter of the macro 
call. 

NOTE 


If you use RSX-11D, you must not allocate an FSR 
block buffer less than 512(decimal) bytes in length 
for spooled output to a record-oriented device (such 
as a line printer). 


The name of the program section (PSECT) to which control returns 
after FSRSZ$ completes processing. If no name is specified, 
control returns to the blank PSECT. 
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2.7.2 FINITS - Initialize FSR at Run Time 


In addition to the FSRSZ$ macro call described in the preceding 
section, the FINITS macro call must also be issued in a MACRO-11 
program to call initialization coding to set up the FSR. This macro 
call takes the following format: 


Format 

label: FINITS 
Parameter 
label 


An optional symbol, which you specify, that allows control to be 
transferred to this location during program execution. Other 
instructions in the program may reference this label, as in the 
case of a program that has been written so that it can be 
restarted. 


The FINITS macro call should be issued in the program's initialization 
code. The first FCS call issued for opening a file performs the FSR 
initialization implicitly (if it has not already been accomplished 
through an explicit invocation of the FINITS$ macro call). However, it 
is necessary, in the case of a program that is written so that it can 
be restarted, to issue the FINITS macro call in the program's 
initialization code, as shown in the second example shown in the third 
paragraph following. This requirement derives from the fact that such 
a program performs all its initialization at run time, rather than at 
assembly time. 


For example, a program that is not written so that it can be restarted 
might accomplish the initialization of the FSR implicitly through the 
following macro call: 


START: OPENSR' #FDBIN ; IMPLICITLY INITIALIZES THE FSR 
;AND OPENS THE FILE. 


In this case, although transparent to you, the OPENSR macro call 
invokes the FINITS$ operation. The label START is the transfer address 
of the program. 


In contrast, a program that embodies the capability to be restarted 
must issue the FINITS macro call explicitly at program initialization 
as shown here: 


START: FINITS ,EXPLICITLY INITIALIZES THE FSR AND 
OPENSR’ #FDBIN ,;OPENS THE FILE. 


In this case, the FINITS macro call cannot be invoked arbitrarily 
elsewhere in the program; it must be issued at program initialization. 
Doing so forces the reinitialization of the FSR, whether or not it has 
been done in a_= previous execution of the program through an OPENSx 
macro call. 


It is important to realize that calling any of the file control 
routines described in Chapter 4, such as .PARSE, first requires the 
initialization of the FSR. However, the FINITS operation must be 
performed only once each program execution. Note also that FORTRAN 
programs issue a FINITS macro call at the beginning of the program 
execution; therefore, MACRO-11 routines used with the FORTRAN object 
time system must not issue a FINITS macro call. 
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2.8 INCREASING THE SIZE OF THE FILE STORAGE REGION 


Procedures for increasing the size of the FSR for either MACRO-11l or 
FORTRAN programs are presented in the Sections 2.8.1 and 2.8.2. 


2.8.1 FSR Extension Procedures for MACRO-11 Programs 


Increase the size of the FSR for a MACRO-1ll program by following 
either of these procedures: 


e Modify the parameters in the FSRSZS$ macro call to redefine the 
buffer pool requirement of files open simultaneously for 
record I/O processing. Reassemble the program. 

e Use the EXTSCT (extend program section) command at’ task-build 
time to define the new size of the FSR. To invoke this 
option, specify the command in the following form: 

EXTSCT = SSFSR1l:length 
Parameter 


SSFSR1 


The symbolic name of the program section within the FSR 
that is reserved as the block buffer pool length. A 
numeric value defining the total required size of the 
buffer pool in bytes. 

The size of the FSR cannot be reduced at task-build time. 


In calculating the total length of the FSR, you can use either of the 
formulas: 


e Length = (S.BFHD*fbufs) tbufsiz 
e Length = fbufs* (S.BFHD+512.) 


Length Argument 


S.BFHD 
A symbol that defines the number of bytes required for 
each block buffer header. You can define this symbol 
locally in your program by issuing the following macro 
call: 


BDOFFS$ DEFSL 


fbhufs 


A numeric value representing either the maximum number of 
files open simultaneously for record I/O (when single 
buffering only is used) or the maximum number of buffers 


ever in use simultaneously among all files open 
concurrently for record I/O (when multiple buffering is 
used). Refer also to the description of this parameter 


in the FSRSZS macro call in Section 2.7.1. 
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bufsiz 


A numeric value defining the total block buffer pool 
space (in bytes) needed to support the maximum number of 
files that can be open simultaneously for record I/O. 
Refer to the description of this parameter in the FSRSZS$ 
macro call in Section 2.7.1. 


512. 
The standard default buffer size. 


The EXTSCT option is described in detail in the RSX-11M/M-PLUS and 
Micro/RSX Task Builder Manual. 


2.8.2 FSR Extension Procedures for FORTRAN Programs 


For a FORTRAN program, if an explicit ACTFIL option is not issued to 
the Task Builder, an ACTFIL statement with a default value of 4 is 
generated during task build. You may extend the size of the FSR at 
task-build time by issuing the command: 


ACTFIL = files 


where files is a decimal value defining the maximum number of files 
that may be open simultaneously for record I/O processing. 


This command, like the EXTSCT command described previously, causes 
program section S$SFSR1 to be extended by an amount sufficient to 
accommodate the number of active files anticipated for simultaneous 
use by the program. 


The size of the FSR for a FORTRAN program can also be decreased at 
task-build time. As noted previously, the default value for the 
ACTFIL command is 4. Thus, if 0, 1, 2, or 3 is specified as _ the 
"files" parameter, the size of S$SFSR1 (the FSR block buffer pool) is 
reduced accordingly. 


The ACTFIL option is described in detail in the RSX-11M/M-PLUS' Task 
Builder Reference Manual. 


2.9 COORDINATING I/O OPERATIONS 


Your programs perform all I/O operations by issuing GETS or PUTS and 
READS or WRITES macro calls. (See Chapter 3 for a complete discussion 
of these file-processing macro calls.) These calls do not access’ the 
physical devices in the system directly. Rather, when any one of 
these calls is issued, an I/O-related system macro called Queue I/0 
(QIOS, QIOSC, or QIOSS) is invoked as the interface between the FCS 
file-processing routines at the user level and the system I/O drivers 
at the device level. Device drivers are included for all the standard 
I/O devices supported by RSX-1l systems. Although transparent to your 
task, the QUEUE I/0 directive is used for all FCS file access 
operations. 


When invoked, the QIOS macro instructs the system to place an I/O 
request for the associated physical device unit into a queue of 
priority-ordered requests for that unit. This request is placed 
according to the priority of the issuing task. As required system 
resources become available, the requested I/O transfer takes place. 
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As implied previously, two separate and distinct processes are 
involved in accomplishing a specified I/O transfer: 


1. The successful queuing of the GETS or PUTS or READS or WRITES 
I/O request 


2. The successful completion of the requested data transfer 
operation 


These processes, both of which yield success/failure indications that 
may be tested by your program, must be performed successfully for the 
specified I/O operation to be completed. It is important to note that 
FCS totally synchronizes record I/0 operations for you, even in the 
case of multiple-buffered operations. In the case of block I/0 
operations, the flexibility of FCS allows you to synchronize all block 
I/O activities, thus enabling you to satisfy logical processing 
dependencies within the program. 


2.9.1 Event Flags 


I/O operations proceed concurrently with other system activity. After 
an I/0 request has been queued, the system does not force an implied 
wait for the issuing task until the requested operation is completed. 
Rather, the operation proceeds in parallel with the execution of the 
issuing task, and it is the task's responsibility to synchronize the 
execution of I/O requests. Tasks use event flags in synchronizing 
these activities. The system executes operations that manipulate, 
test, and wait for these indicators of internal task activity. 


The completion of an I/O transfer, for example, is recognized by the 
system as a significant event. If you have specified a particular 
event flag to be used by the task in coordinating I/0-completion 
processing, that event flag is set, causing the system to evaluate the 
eligibility of other tasks to run. Any event flag from 1 through 
32(decimal) may be defined for local use by the task. If you have not 
specified an event flag, FCS uses event flag 32(decimal) by default to 
signal the completion of I/O transfers. 


Specific FDB-initialization and I/O-initiating macro calls in FCS 
enable you to specify event flags, if desired, that are unique to a 
particular task and that are set and reset only as a result of that 
task's operation. 


For record I/O operations, such an event flag may be defined through 
the efn parameter of the FDBFSA or the FDBFSR macro call (see Section 
2.3.1.6 or 2.3.2, respectively). 


For block I/0 operations, an event flag may be declared through the 
bkef parameter of the FDBKSA or the FDBKSR macro call (see Section 
2.3.1.4 or 2.3.2, respectively); alternatively, a block event flag may 
be declared through the corresponding parameter of the 1/0-initiating 
READS or WRITES macro call (see Section 3.15 or 3.16, respectively). 


In both record and block I/O operations, the event flag is cleared 
when the I/0 request is queued and set when the I/O operation is 
completed. In the case of record I/O operations, only FCS manipulates 
the event flag. Additionally, the event flag's state is transparent 
to your task, which must not issue a WAITFOR system directive 
predicated on the event flag used for coordinating record I/0 
operations. A record I/O operation, for example, may not even involve 
an I/0 transfer; rather, it may only involve the blocking or 
deblocking of a record within the FSR block buffer. On the other 
hand, the event flag defined for synchronizing block I/O operations is 
totally under your control. 
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Also, a code indicating the success or failure of the QIOS macro 
request resulting from the READS or WRITES macro call is returned to 
the Directive Status Word (SDSW). If desired, symbolic location SDSW 
may be tested to determine the status of the I/O request. The 
success/failure codes for the QIOS macros are listed in the 
RSX-11M/M-PLUS I/O Drivers Reference Manual and the Micro/RSX I/0 
Drivers Reference Manual. > 


Event flag directives are described in the RSX-11M/M-PLUS and 
Micro/RSX Executive Reference Manual. The relationship of event flags 
to specific devices is described in the RSX-l11M/M-PLUS 1/0 Drivers 
Reference Manual and the Micro/RSX I/O Drivers Reference Manual. 


2.9.2 I/0 Status Block 


Because of the comparative complexity of block I/O operations, an 
optional parameter is provided in the FDBKSA and the FDBKSR macro 
calls, as well as in the READS and WRITES macro calls, that enables 
the system to return status information to your task for block I/0 
operations. The I/O status block is not applicable to record I/0 
(GETS or PUTS) operations. 


This optional parameter, called the I/O status block address, is made 
available to FCS through any of the macro calls identified previously. 
When this parameter is supplied, the system returns status information 
to a 2-word block reserved in your program. Although the I/O status 
block is used principally as a QIO$ macro housekeeping mechanism for 
containing certain device-dependent information, this area also 
contains information of particular interest to you. 


Specifically, the second word of the I/O status block is filled in 
with the number of bytes transferred during a READS or WRITES 
operation. When you are performing READS operations, it is good 
practice to use the value returned to the second word of the I/0 
status block as the number of bytes actually read, rather than _ to 
assume that the requested number of bytes was transferred. Employing 
this technique allows the program to properly read virtual blocks of 
varying length from a device such as a magnetic tape unit, provided 
that the requested byte count is at least as large as the largest 
virtual block. For WRITES operations, the specified number of bytes 
is always transferred; otherwise, an error condition exists. 


Also, the low-order byte of the first word of the I/O status’ block 
contains a code that reflects the final status of the READS or WRITES 
Operation. The codes returned to this byte may be tested to determine 
the status of any given block I/O transfer. The binary values of 
these status codes always have the following significance: 


Code Value Meaning 
+ I/O transfer completed 
0 I/O transfer still pending 


- I/O error condition exists 


The format of the I/O status block and the error codes returned to the 
low-order byte of its first word are described in detail in the 
RSX-11M/M-PLUS I/O Drivers Reference Manual or the Micro/RSX I/0 
Drivers Reference Manual. - | 
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If the address of the I/O status block is not made available to FCS 
(and hence to the QIO$ macro) through any of the macro calls noted 
previously, no status information is returned to the I/O status block. 
In this case, the fact that an error condition may have occurred 
during a READS or WRITES operation is simply lost. Thus, supplying 
the address of the I/O status block to the associated FDB is highly 
desirable and makes normal error reporting easier. 


An I/O status block may be defined in your task at assembly time 
through any storage directive logically equivalent to the following: 


IOSTAT: .BLKW 2 


where IOSTAT is a symbol, which you define, naming the I/0 status 
block and defining its address. This symbolic value is specified as 
the bkst parameter in the FDBKSA or the FDBKSR macro call to 
initialize FDB offset location F.BKST; it may also be specified as the 
corresponding parameter in the READS or the WRITES macro call. 
Initializing this cell in the FDB is an integral part of issuing the 
desired I/O request. 


2.9.3 AST Service Routine 


An asynchronous system trap (AST) is a software-generated interrupt 
that causes the sequence of instructions currently being executed to 
be interrupted and control to be transferred to another instruction 
sequence elsewhere in the program. If desired, you may specify the 
address of an AST service routine that is to be entered upon 
completion of a block I/O transfer. Because an AST is a trap action, 
it constitutes an indication of block I/O completion. 


The address of an AST service routine may be specified as an optional 
parameter (bkdn) in the FDBKSA or the FDBKSR macro call (see Section 
2.3.1.4 or 2.3.2, respectively); this parameter may also be specified 
in the READS or the WRITES macro call, initializing the FDB at the 
time the I/0 request is issued (see Section 3..15 or 3216; 
respectively). 


Usually, an AST address is specified to enable a running task to be 
interrupted to execute special code upon completion of a block I/0 
request. If the address of an AST service routine is not specified, 
the transfer of control does not occur, and normal task execution 
continues. 


The main purpose of an AST service routine is to inform your task that 
a block I/O operation has been completed, thus enabling the program to 
continue immediately with some other desired (and perhaps’ logically 
dependent) operation (for example, another I/O transfer). 


If an AST service routine is not provided by you, some other 
mechanism, such as event flags or the I/O status block, must be used 
as a means of determining block I/0 completion. In the absence of 
such a routine, for example, you may test the low-order byte of the 
first word in the I/O status block to determine if the block 1/0 
transfer has been completed. A WAITS macro call (see Section 3.17) 
may also be issued in connection with a READS or WRITES operation to 
suspend task execution until a specified event flag is set to indicate 
the completion of block I/O. 
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Implementing an AST service routine in your program is application 
dependent and must be coded specifically to meet your task's 
particular I/O-processing requirements. A detailed discussion of 
asynchronous system traps is beyond the scope of this document. Refer 
to the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual _ for 
discussions of trap-associated system directives. 


CAUTION 


Do not execute any FCS routines while in an AST 
service routine. FCS maintains an impure data 
area that it uses as a Directive Parameter Block 
and aS a scratch area for directives. An AST 
could interrupt an FCS operation that is altering 
this impure area. Executing an FCS routine in AST 
state could alter the impure area and cause 
unpredictable results when task execution resumes. 


2.9.4 Block Locking 


Block locking selectively controls access to blocks within a file 
while that file is being read from or written to by one or more users. 
Block locking can be used from FCS or RMS-ll, or by issuing QIO$ 
macros. 


You can enable block locking only when the file is opened. Once block 
locking is enabled, you can establish “locks," which are structures 
allocated from system dynamic storage that control access to specific 
blocks in the file. 


When your task reads or writes a block, the Executive creates a lock 
that subsequently restricts other users from writing to or reading 
from that block. When your task has a file open on a LUN with block 
locking enabled and locks are created, your locks do not restrict your 
task from reading or writing blocks if you use the same LUN. Locks 
may be selectively eliminated by issuing a QIOS macro with the IO.ULK 
(unlock) function code. You can only eliminate those blocks that you 
have created. When your task closes the file, all your locks on that 
file are released to system dynamic storage. 


Block locking operates in the following ways when using FCS: 
1. Opening the File: 


To enable block locking when opening a file from FCS, you 
must change two fields in the File Descriptor Block. The 
value FA.SHR in byte F.FACC must be set to allow shared write 
access to the file. Additionally, the values FA.LKL, FA.EXL, 
and FA.ENB must be set in word F.ACTL. Setting FA.SHR causes 
FCS to clear AC.LCK in the DPB. For example: 


FDOPSR #FDB,,,,#FA.SHR,#FA.LKL!FA.EXL!FA.ENB 
OPENSR ROsveeree ss ERRSUB ;OPEN SHARED FOR READ WITH LOCKS 


2. Writing or Reading Blocks: 


A one-block read or write operation locks a block for 
exclusive access. A write or read operation of more than one 
block similarly locks all blocks operated on in this QIOS 
macro. A file open for block mode may invoke READS and 
WRITES macros in the usual manner. 
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Note that, in general, FCS operates as follows on sequential 
read access: 


a. OPENSR positions the file to record 1 

b. GETS returns record 1 and positions the file to record 2 
c. GETS returns record 2 and positions the file to record 3 
d. GETS returns record 3 and positions the file to record 4 


Be aware that successive GETS macros scan across the file 
sequentially. 


However, if you have files open for record mode operations, 
the following special considerations may exist: 


e A number of tasks are updating records in a single file 
e One of these tasks is reading records sequentially 


For example, if the GETS macro for record 2 in the task that 
reads blocks sequentially fails because record 2 is contained 
in a block previously locked by another task, FCS loses its 
position in the file. The next GETS macro yields undefined 
results; it obtains neither record 2 nor record 3. 


After this kind of error occurs, FCS must reposition its 
pointer to the records in the file. This can happen in one 
of the following ways: 


@e Operating in random mode on fixed-length records, FCS 
repositions its record pointer to the first record for 
each GETS or PUTS operation. 


e FCS repositions the FCS pointer in a file of 
variable-length records by calling the FCS .POINT routine. 
You can reposition the pointer either to a location noted 
by a previous .MARK call, or to the beginning of the file. 


e FCS closes and reopens the file to reposition the pointer 
to the beginning. 


Unlocking Blocks: 


To unlock blocks without closing the file, you must execute a 
QIOS macro with the function code IO.ULK. You can use I0.ULK 
to unlock one block, a series of blocks, or all the blocks in 
an open file. 


To unlock one or more blocks in a series, specify the block 
count in device-dependent parameter Word 2, specify the high 
8 bits of the starting VBN in the low byte of parameter Word 
4, and specify the low 16 bits of the starting VBN in 
parameter Word 5. For example, to unlock previously locked 
VBNs 5, 6, and 7, use the following code: 


MOV #3,R0 ;UNLOCK 3 BLOCKS 
MOV #5,R1 ;STARTING AT VBN 5 
QIOWSS #I1O0.ULK, #MYLUN, #1,,#IOSB,,<,RO,,,R1> 
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To unlock all blocks you have locked on this LUN, issue _ the 
QIO$ macro with no parameters beyond the device-independent 
part of the DPB, as follows: 


QIOWSS #I0O.ULK, #MYLUN, #1,,#IOSB ;UNLOCK ALL BLOCKS 


Also, you can use FCS to execute the QIOS macros for you by 
calling the .XIOU routine. 


To use the .XIOU routine to unlock all blocks that you have 
locked on this LUN and file, call .XQIO with no option 
parameters, that is, with R2=0 as follows: 


MOV #FDB,RO ;GET FDB ADDRESS 

MOV #IO.ULK ;UNLOCK BLOCK FUNCTION 

CLR R2 ;UNLOCK ALL BLOCKS 

CALL - XQIO ;EXECUTE QIO 

BCS ERROUT ;IF CS ERROR IS IN F.ERR (RO) 


To use .XIOU to unlock one or more blocks in a= series, you 
must set up a 5-word parameter block. Specify the count of 
blocks in Word 2, specify the high 8 bits of the starting VBN 
in the low byte of parameter Word 4, and specify the low 16 
bits of the starting VBN in parameter Word 5. For example, 
to unlock the previously locked VBNs 5, 6, and 7, use the 
following code: 


PRMBK: .WORD 0 ;PARAMETER BLOCK FOR UNLOCK QIO 
-WORD 0 ;COUNT OF BLOCKS TO UNLOCK 
-WORD 0 : 

-WORD 0 ;HIGH 8 BITS OF START VBN 
~WORD 0 ;LOW 16 BITS OF START VBN 
MOV #FDB,RO 7GET FDB ADDRESS 

MOV #IO0.ULK ;UNLOCK BLOCK FUNCTION 

MOV #5,R2 ;FIVE PARAMETERS 

MOV #PRMBK,R3 ;ADDRESS OF PARAMETER BLOCK 
MOV #3,2(R3) ;UNLOCK 3 BLOCKS 

MOV #5,8. (R3) ;STARTING AT VBN 5 

CALL -XQIO ,;EXECUTE QIO 

BCS ERROUT ;IF CS ERROR IS IN F.ERR (RO) 


4. Closing the Files 
Closing the file in the ordinary manner will release all 


blocks that have been established on that file for the 
specific task and LUN. 


2.9.5 Error Codes Related to Shared Files and Block Locking 


Error codes relating to file sharing and block locking may be returned 
in the following circumstances: 


1. Opening the File 
IE.WAC 
Indicates that you have requested that other users’ be 


denied write access (no FCS FA.SHR or AC.LCK=1), but 
someone else has already opened the file to write to it. 


PREPARING FOR 1/0 


Solutions Do not attempt to open the file until all 
others writing to the file have closed it. 


IE.LCK 
Indicates that one of the following conditions is true: 


e You want to write to the file and have allowed shared 
write access (set FCS FA.SHR or AC.LCK=0), but 
someone else has already opened the file denying 
others write access. : 


Solution: Do not attempt to open the file until all 
accessors without shared write access have closed the 
file. 


@e You want to write to the file and have allowed shared 
write access (set FCS FA.SHR or AC.LCK=0) without 
enabling block locking but someone else has already 
opened the file with block locking enabled. 


Solution: Open the file with block locking enabled. 


@ F11ACP cannot perform a directory operation because 
the directory is locked or being written to. 


Solution: The solution depends on what you 
anticipate as normal activity on your system. If it 
is legitimate for a task to access a directory, then 
consider attempting the operation again. 


IE.ULK 
Indicates that the Executive does not support block 
locking. This error can only be returned on an RSX-11M 


system that has been generated without block locking 
support. 


Solution: Open the file without enabling block locking. 
Writing or Reading Blocks: 

IE.ULK 

Returned by the Executive when any read or write error 
occurs that relates to block locking. It generally 
means that another task has locked the block. 

Solution: The solution depends on the application. 
Wait and retry the operation or report the error and 
stop processing. 

Unlocking Blocks: 

IE.IFC 


Returned when the Executive does not support block 
locking. 


Solutions Do not attempt to unlock blocks on a_ system 
that does not support block locking. 


IE.LCK 
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Returned upon the occurrence of any other error. For 
example, IE.LCK is returned if another task has locked 
the blocks. 


Solutions: Unlock only those blocks that you have 
previously locked for that file. 


Closing the File: 


No block locking error can occur when closing a file. 


CHAPTER 3 


FILE-PROCESSING MACROS 


You can manipulate files through a set of file-processing macro calls. 
The assembler invokes and expands these macros at assembly time and 
the operating system executes the resulting code at run time. This 
chapter describes these run-time macro calls, which allow you to 
manipulate files and to perform the following I/O operations: 


OPENS - Opens and prepares a file for processing 


OPNSS 


Opens and prepares a file for processing and to allow 
shared access to that file (depending on the mode of 


access) 
OPNTS - Creates and opens a temporary file for processing 
OFIDS - Opens an existing file using file identification 


information in the filename block 


OFNBS - Opens a file using file name information in the 
filename block 


CLOSES - Terminates file processing in an orderly manner 

GETS - Reads logical data records from a file 

GETSR - Reads fixed-length records from a file in random mode 

GETSS - Reads records from a file in sequential mode 

PUTS - Writes logical data records to a file 

PUTSR - Writes fixed-length records to a file in random mode 

PUTSS ~ Writes records to a file in sequential mode 

READS - Reads virtual data blocks from a file 

WRITES - Writes virtual data blocks to a file 

DELET$ - Removes a named file from the associated volume 
directory and deallocates the space occupied by the 
file 

WAITS - Suspends program execution until a requested block I/0 


operation is completed 


Most of the parameters associated with the file-processing macro calls 
supply information to the File Descriptor Block (FDB). Such 
parameters cause MOV or MOVB instructions to be generated in the 
object code, resulting in the initialization of specific locations 
within the FDB. 
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The final parameter in all file-processing macros is the symbolic 
address of an optional, user-defined error-handling routine. This 
routine is entered upon detection of an error condition during the 
file-processing operation. When this optional parameter is specified, 
the following code is generated: 


Code for macro 


BCC nns ;TESTS CARRY BIT IN PROCESSOR STATUS 
WORD. 
JSR PC,ERRLOC ;INITIATES ERROR-HANDLING ROUTINE 
;AT "“ERRLOC" ADDRESS. 
nnS$: ;CONTINUES NORMAL PROGRAM EXECUTION. 


where nn$ represents a generated local symbol. If the operation is 
completed successfully, the Carry bit in the Processor Status Word is 
not set, and FDB offset location F.ERR contains a positive value. The 
BCC instruction then results in a branch to the local symbol nn$ and 
the continuation of normal program execution. 


However, if an error condition is detected during the execution of the 
file-processing routine, the Carry bit in the Processor Status Word is 
set, FDB offset location F.ERR contains a negative value (indicating 
an error condition), and the branch to the local symbol nnS$ does not 
occur. Instead, the JSR instruction is executed, loading the PC with 
the symbolic address (ERRLOC) of the error-handling routine and 
initiating its execution. 


If this optional parameter is not specified, the error-processing 
routine is not called, and you must explicitly test the Carry bit in 
the Processor Status Word to ascertain the status of the requested 
operation. 


Note that executing the FCS file-processing routines causes all your 
task's general registers to be saved except RO. FCS uses RO by 
convention to contain the address of the FDB associated with the file 
being processed. 


3.1 OPENSX - GENERALIZED OPEN MACRO 


Before any file can be processed by your task or system program, it 
must first be opened. An alphabetic suffix accompanying the macro 
name indicates to FCS the action you intend to perform on a file. For 
example, in issuing the following generalized macro: 

OPENSx 


x represents any one of the following alphabetic suffixes, each of 
which denotes a specific type of file processing: 


R - Read an existing file 


W 


Write (create) a new file 


M - Modify an existing file without changing its length 
U - Update an existing file and extend its length, if necessary 
A - Append (add) data to the end of an existing file 
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NOTE 


You can issue the generalized OPEN$x macro without an 
alphabetic suffix. In this case, the action to be 
performed on the file is indicated to FCS through an 
additional parameter in the macro. This value, called 
the file access (facc) parameter, causes offset 
location F.FACC in the associated FDB to be 
initialized. Section 3.7 describes this macro in 
detail. 


Depending on the alphabetic suffix supplied in the OPENSx macro call, 
certain other types of operations may or may not be allowed, as noted 
here: 


1. If R is specified (for reading an existing file), that file 
cannot also be written; that is, a PUTS or WRITES operation 
cannot be performed on that file. 


2. If M or U is specified (for modifying or updating an existing 
file), that file can be both read and written; that is, 
concurrent GETS and PUTS or READS and WRITES operations can 
be performed on that file. 


3. If M is specified (for modifying an existing file), that file 
cannot be extended. 


4. If Wor A is specified (for creating a new file or appending 
data to an existing file), that file can be read, written, or 
extended. 


The program that issues the OPENSx macro must have appropriate access 
privileges for the specified action. Table 3-1 summarizes the access 
privileges for the various forms of the OPENS$x macro. This table also 
shows where the next record or block will be read or written in the 
file after it is opened. 


Table 3-1 
File Access Privileges Resulting from OPENS$x Macro 


Macro Access Privileges Position Of File After OPENSx 
OPENSR Read First record of existing file 
OPENSW Read, write, extend First record of new file 
OPENSM Read, write First record of existing file 
OPENSU Read, write, extend First record of existing file 
OPENSA Read, write, extend End of existing file (For 


special PUTSR considerations, 
see Section 3.13.) 


When your task issues any form of the OPENSx macro, FCS first fills in 
the filename block with file name information retrieved from the 
dataset descriptor (see Section 2.4.1). FCS gains access to this data 
structure through the address value stored in FDB offset location 
F.DSPT. 


FILE-PROCESSING MACROS 


If any required data has been omitted from the dataset descriptor, FCS 
attempts to obtain the missing information from the default filename 
block. This data structure, which may also contain file name 
information specified in your task, is created in the program by 
issuing the NMBLKS macro (see Section 2.4.2). FCS gains access’ to 
this structure through the address value stored in FDB offset location 
F.DFNB. 


The address values in offset locations F.DSPT and F.DFNB can be 
supplied to FCS through the FDOPSA macro, the FDOPSR macro call, or 
the OPENSx macro. FCS requires access to the Dataset Descriptor or 
the default filename block in retrieving file name information used in 
opening files. 


If a new file is to be created, the OPENSW macro is issued. FCS’ then 
performs the following operations: 


l. Creates a new file and obtains file identification 
information for the file. FCS maintains the file 
identification information in offset location N.FID of the 
filename block. The filename block in the FDB begins at the 
FDB offset location F.FNB. 


2. Initializes the file attribute section of the file header 
block. The file header, block is a file system structure 
maintained on the volume containing the file. Each file ona 
volume has an associated file header block that describes the 
attributes of that file. FCS obtains attribute information 
for a new file from the FDB associated with the file. The 
format and content of a file header block are presented in 
detail in Appendix F. 


3. Places an entry for the file in the User File Directory 
(UFD). If, however, an entry for a file having the same 
name, type, and version number already exists in the UFD, the 
old file is deleted. If your task explicitly issues a 
particular type of macro that specifies that the file not be 
superseded, the old file is not deleted and an error code is 
returned. This type of OPENS operation is described in 
Section 3.7. 


4. Associates the assigned logical unit number (LUN) with the 
file to be created. 


5. Allocates a buffer for the file from the FSR block buffer 
pool if record I/O (GETS or PUTS) operations are processing 
the file. 


If an existing file is to be opened, any one of the following macros 
may be issued: OPENSR, OPENSM, OPENSU, or OPENSA. FCS then performs 
the following operations: 


l. If file identification information is not present in the 
filename block, FCS constructs the filename block from 
information taken from the dataset descriptor and the default 
filename block, or both. FCS then searches the UFD by file 
name to obtain the required file identification information. 
When found, this information is stored in the filename block, 
beginning at offset location N.FID. 


2. Associates the assigned logical unit number (LUN) with the 
file. 


3. Reads the file header block and initializes’ the file 
attribute section of the FDB associated with the file being 
opened. 


FILE-PROCESSING MACROS 


4. Allocates a buffer for the file from the FSR block buffer 


pool if record I/O (GETS or PUTS) operations are processing 
the file. 


NOTE 


As described in Section 2.6, you allocate buffers 
through the FSRSZS$ macro. The number of buffers 
allocated is dependent upon the number of files that 
you intend to open simultaneously for record I/0 
operations. 


If your task uses block I/O operations, FDB offset location F.RACC 
must be initialized with the FD.RWM parameter by the FDRCSA, the 
FDRCSR, or the generalized OPENSx macro. This parameter inhibits the 
allocation of a buffer when the file is opened. 


3.1.1 Format of Generalized OPENSx Macro 


The OPENSx macro takes the following general form: 


Format 


OPENSx fdb,lun,dspt,racc,urba,urbs,err 


Parameters 


x 


fdb 


lun 


dspt 


The alphabetic suffix specified as part of the macro name, 
indicating the desired type of operation to be performed on the 
file. The possible values for this parameter are: R, W, M, U, 
or A (see Section 3.1). 


A symbolic value of the address of the associated FDB. 


The logical unit number (LUN) associated with the desired file. 
This Parameter identifies the device on which the volume 
containing the desired file is mounted. Normally, the logical 
unit number associated with the file is specified through the 
corresponding parameter of the FDOPSA or the FDOPSR macro. If so 
specified, the lun parameter need not be present in the OPENSx 
macro. Each FDB must have a unique LUN. 


The symbolic address of the dataset descriptor. Normally, this 
address value is specified through the corresponding parameter of 
the FDOPSA or the FDOPSR macro. If so specified, this parameter 
need not be present in the OPENSx macro. 


This parameter specifies the address of the manually created 
dataset descriptor (see Section 2.4.1). If the Command String 
Interpreter (CSI) interprets command lines dynamically, this 
parameter specifies the address of the dataset descriptor within 
the CSI control block (see offset location C.DSDS in Section 
6.2.2). 


racc 


urba 


urbs 
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The record access byte. One or more symbolic values may _ be 
specified in this field to initialize the record access byte 
(F.RACC) in the associated FDB. You can specify any combination 
of the following parameters by separating them with exclamation 
points: 


e FD.RWM - Requests that block I/O (READS or WRITES) operations 
are to process the file. If you do not specify this 
parameter, FCS assumes by default that record I/O (GETS or 
PUTS) operations are to process the file. 


e FD.RAN - Requests random access to the file for record I/0 
(GETS or PUTS) operations. The file is opened and the first 
record is pointed to. With this parameter, a PUTS operation 
in the file, without exception, does not truncate the file. 
If this parameter is not specified, FCS uses sequential access 
by default. Refer to Section 1.5 for a description of random 
access mode. 


e FD.PLC - Requests locate mode (see Section 1.6.2) for record 
I/O (GETS or PUTS) operations. If this parameter is not 
specified, FCS uses move mode (see Section 1.6.1) by default. 


e FD.INS - Requests that a PUTS operation in sequential mode in 
the body of a file shall not truncate the file. Effectively, 
this parameter prevents the logical end of the file from being 
reset to a point just beyond the inserted record. If this 
parameter is not specified, a PUTS operation in sequential 
mode truncates the file to a point just beyond the inserted 
record, but no deallocation of file blocks occurs. 


Specifying this parameter allows a data record in the body of the 
file to be overwritten. Care must be exercised, however, to 
ensure that the record being written is the same length as_ that 
of the record being replaced. 


If the record access byte in the FDB has already been initialized 
through the corresponding parameters of the FDRCSA or the FDRCSR 
macro, the racc parameters need not be present in the OPENSx 
macro. 


The symbolic address of your task's record buffer. This 
parameter initializes FDB offset location F.URBD+2. 


If your task's record buffer address has already been supplied to 
the FDB through the corresponding parameter of the FDRCSA or the 
FDRCSR macro, this parameter need not be present in the OPENSx 
macro. 


A numeric value defining the size of your task's record buffer 
(in bytes). This parameter initializes FDB offset location 
F.URBD. 


If the size of your task's record buffer has already been 
supplied to the FDB through the corresponding parameter of the 
FDRCSA or the FDRCSR macro, this parameter need not be present in 
the OPENSx macro. 
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err 


The symbolic address of an optional user-coded error-handling 
routine. 


Specific FDB requirements for record I/O operations (GETS and PUTS 
macros) are detailed in Sections 3.9.2 and 3.12.2. 


The following examples show sample uses of the OPENSx macro. 


A macro to open and modify an existing file, for example, might take 
the following form: 


OPENSM RO, #INLUN,, #FD.RAN! FD. PLC 


Note in this macro that the FDB address is assumed to be present in 
RO. The third parameter, that is, the dataset descriptor pointer, is 
not specified; this null specification (indicated by the extra comma) 
assumes that FDB offset location F.DSPT (if required) has already been 
initialized. The last parameter, consisting of two values separated 
by an exclamation point, establishes random access and locate modes 
for GETS or PUTS operations. 


The following macro might be issued to update an existing file: 
OPENSU RO,#INLUN,,, #RECBUF, #80. 


This macro also assumes that the FDB address is in RO. Note also that 
the dspt and racc parameter fields are null, based on the premise that 
the dataset descriptor pointer (F.DSPT) has been provided previously 
to the FDB and that the record access byte (F.RACC) has also been 
previously initialized. Finally, the last two parameters establish 
the address and the size, respectively, of your task's record buffer. 


This last example shows a macro that might be issued to allow data to 
be appended to the end of a file: 


OPENSA #OUTFDB 
This macro specifies the address of an FDB as the only parameter. In 
this case, it is assumed that all other parameters required by FCS in 
opening and operating on the file have been previously supplied to the 
FDB through the appropriate assembly-time or run-time macro. 
Note in all three preceding examples that the error parameter is not 
specified, requiring that you explicitly test the Carry bit in the 


Processor Status Word to ascertain the success of the specified 
operation. 


NOTE 
You can use RO only to pass the FDB address parameter. 


Any other use of RO when you issue the OPENSA macro 
will fail. 


3.1.2 FDB Requirements for Generalized OPENSx Macro 


The information required for opening a file may be supplied to the FDB 
through the following macros: 


e The assembly-time macros described in Section 2.2.1 


e The NMBLKS macro described in Section 2.4.2 
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e The run-time macros described in Section 2.2.2 
e The various macros described in this chapter for opening files 


Using any particular combination of macros to define and initialize 
the FDB is a matter of choice, as indicated previously. Of far 
greater significance is the fact that certain information must be 
present in the FDB before you can open the associated file. In this 
regard, the following rules apply for creating and opening new files, 
for opening existing files, and for specifying desired file options: 


l. To Create a New File 


If a new file is to be created through the OPENSW macro, the 
following information must first be supplied to the FDB. You 
can specify this information through the FDATSA macro (see 
Section 2.2.1.2) or the FDATSR macro (see Section 2.2.2): 


e The record type must be established for record I/0 
operations. 


The record type cannot be supplied to the FDB through any 
of the various macros used to create or open files (for 
example, OPENSW, OPENSR, and so forth). Furthermore, this 
information is required when opening an existing file, 
because FCS obtains such information from the first 14 
bytes of your task's file attribute section of the file 
header block (see Appendix F). 


To establish the record type, you must initialize byte 
offset location F.RTYP with the following symbolic values: 


- R.FIX ~ Requests that fixed-length records are to be 
written into the file. 


- R.VAR - Requests that variable-length records are to be 
written into the file. 


- R.SEQ - Requests that sequenced records are to be 
written into the file. 


@e The desired record attributes must be specified for record 
I/O operations. 


The record attributes cannot be supplied to the FDB 
through any of the various macros used to create or open 
files (for example, OPENSW, OPENSR, and_ so forth). 
Furthermore, the record attributes are required when 
opening an existing file, because FCS obtains such 
information from the first 14 bytes of your task's file 
attribute section of the file header block (see Appendix 
F). 


The record attributes are defined by initializing byte 
offset location F.RATT with the appropriate value(s), as 
follows: 


- FD.FTN - Requests that the first byte of each’ record 
contain a FORTRAN carriage-control character. 


- FD.CR - Requests that a line-feed (<LF>) character 
precede each record and that a carriage-return (<CR>) 
character follow the record when that record is output 


FILE-PROCESSING MACROS 


to a device requiring carriage control information (for 
example, to a terminal). The <LF> and <CR> characters 


are not actually embedded within the record. Their 
presence is merely implied through the file attribute 
FD.CR. 


- FD.BLK - Requests that records’ be prevented from 
crossing block boundaries. 


-~ FD.PRN - Requests that the record be preceded by a word 
containing carriage-control information. Files with 
this attribute must also be sequenced files; that is, 
files with the bit R.SEQ set in the byte F.RTYP in the 
FDB. For more information about FD.PRN as aé_e record 
attribute, see Chapter 2, Section 2.2.1.2. 


If fixed-length records are to be written to the file, you 
must specify the record size (in bytes) for record I/0 
operations to appropriately initialize FDB offset location 
F.RSIZ. 


The record size cannot be supplied to the FDB through any 
of the various macros used to create and open files, or 
both (for example, OPENSW, OPENSR, and so forth). 
Furthermore, the record size is required when opening an 
existing file, because FCS obtains such information from 
the first 14 bytes of your task's file attribute section 
of the file header block (see Appendix F). 


To Open Either a New File or an Existing File 


Regardless of whether the file being opened is yet to _ be 
created or already exists, the following information must be 
present in the FDB before that file can be opened: 


The record access byte must be initialized for record or 
block I/O operations. The symbolic values following may 
be specified in the FDRCSA macro (see Section 2.2.1.3), 
the FDRCSR macro call (see Section 2.2.2), or the 
generalized OPENSx macro to initialize FDB offset location 
F.RACC: 


- FD.RWM - Requests that READS or WRITES (block I/O) 
operations process the file. If this parameter is not 
specified, GETS or PUTS (record I/0) operations result 
by default. 


- FD.RAN - Requests that random access mode (GETS or PUTS 
record I/0) process the file. The file is opened and 
the first record pointed to. If this parameter is not 
specified, sequential access mode results by default. 
Refer to Section 1.5 for a description of random access 
mode. 


- FD.PLC - Requests that locate mode (GETS or PUTS record 
I/O) process the file. If this parameter is not 
specified, move mode results by default. 


- FD.INS - Requests that a PUTS operation in sequential 
mode in the body of a file shall not truncate the file. 
If this parameter is not specified, a PUTS operation 
truncates the file. In this case, the logical end of 
the file is reset to a point just beyond the inserted 
record, but no deallocation of file blocks occurs. 
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e Your task's record buffer descriptors (that is, the urba 
and urbs parameters) must be specified for record I/0 
operations. To accomplish this, the FDRCSA, the FDRCSR, 
or the generalized OPENSx macro may be used. The selected 
macro call defines the address and the size of the area 
reserved in the program for use as a buffer during record 
I/O operations. The urba and urbs parameters initialize 
FDB offset locations F.URBD+2 and F.URBD, respectively. 


FDB requirements specific to GETS and PUTS operations in 
move and locate mode are presented in detail in Sections 
3.9.2 and 3.12.2, respectively. 


@ You must specify the logical unit number to initialize FDB 
offset location F.LUN. Initializing this cell can be 
accomplished with the lun parameter of the FDOPSA, the 
FDOPSR, or the generalized OPENSx macro. Each FDB must 
have a unique logical unit number. 


e If file identification information is not already present 
in the FDB, either the dataset descriptor pointer (F.DSPT) 
or the default filename block address (F.DFNB) must _ be 
specified to enable FCS to obtain required file name 
information for use in opening the file. These address 
values may be specified in either the FDOPSA macro (see 
Section 2.1.1.5) or the FDOPSR macro (see Section 2.2.2). 
The generalized OPEN$x macro (see Section 3.1) may also be 
used to specify the dataset descriptor pointer. 


e If desired, an event flag number for synchronizing record 
I/O operations must be specified to initialize FDB offset 
location F.EFN. This optional parameter may be specified 
in either the FDBFSA macro (see Section 2.2.1.6) or the 
FDBFSR macro (see Section 2.2.2). If not specified, FCS 
uses event flag number 32(decimal) by default in 
synchronizing all record I/O activity. 


To Specify Desired File Options - 


If certain options are desired for a given file, they must be 
specified before that file is opened. Because this 
information is needed only in opening the file, it is zeroed 
when the file is closed, thus ensuring that the FDB is 
properly reinitialized for subsequent use. The options’ that 
may be specified for a given file are described here: 


e The override block size (ovbs parameter) must be specified 
in either the FDBFSA or the FDBFSR macro to initialize FDB 
offset location F.OVBS. This parameter need be specified 
only if the standard default block size in effect for the 
associated device is to be overridden or if the 
big-buffering or multiple-buffering versions of FCS are in 
use. The override block size is specified to improve 1/0 
system performance with record I/O, and with 
record-oriented devices (such as_ line printers) and 
sequential devices (such as magnetic tape units). (See 
Section 2.2.1.6.) 


e The multiple buffer count (mbct parameter) must be 
specified in either the FDBFSA or the FDBFSR macro to 
initialize FDB offset location F.MBCT. If 
multiple-buffered record I/O operations are to be used, 
this parameter must be greater than 1, and it must agree 
with the desired number of buffers to be used. This 
parameter is neither overlaid nor zeroed when the file is 
closed. 
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If the multiple buffer count is not established as 
described previously, multiple-buffered operations can 
still be invoked by changing the default buffer count in 
the FSR. A default buffer count of 1 is stored in 
symbolic location .MBFCT of SSFSR2. This default value 
can be altered to reflect the number of buffers intended 
for use during record I/O operations. The procedure for 
modifying this cell in $S$FSR2 is described at the end of 
Section 2.2.1.6. 


In addition, if your task uses multiple buffering, you 
Must specify the appropriate control flag as the mbfg 
Parameter in either the FDBFSA or the FDBFSR macro_ to 
appropriately initialize FDB offset location F.MBFG. 
Either of two symbolic values may be specified for this 
purpose, as follows: 


- FD.RAH - Requests that read-ahead operations are _ to 
process the file. 


- FD.WBH - Requests that write-behind operations are _ to 
process the file. 


Offset location F.MBFG need be initialized only if the 
standard default buffering assumptions are inappropriate. 
When a file is opened for reading (OPENSR), read-ahead 
operations are assumed by default; for all other forms of 
OPENSx, write-behind operations are assumed. It may be 
useful, for example, to override the write-behind default 
assumption for a file opened through the OPENSM or _ the 
OPENSU macro when that file is being used basically for 
sequential read operations, but scattered updating is also 
being performed. 


To allocate required file space at the time a file is 
created, the cntg parameter must be specified in either 
the FDATSA or the FDATSR macro. This parameter 
initializes FDB offset location F.CNTG. A positive value 
so specified results in the allocation of a contiguous 
file having the specified number of blocks; a negative 
value, on the other hand, results in the allocation of a 
noncontiguous file having the specified number of blocks. 


The address of the 5-word statistics block in your program 
must be moved manually into FDB offset location F.STBK. 
This address value specifies an area in your task to which 
FCS returns certain statistical information about a file 
when it is opened. If this parameter is not specified, no 
return of such information occurs. 


The format and content of the statistics block are 
presented in Appendix H. You can define such an area ina 
program with coding logically equivalent to 


STBLK: .BLKW 5 


Offset location F.STBK may then be manually initialized, 
as follows: 


MOV #STBLK,FDBADR+tF STBK 


where STBLK is the symbolic address of the statistics 
block, which you define, and the destination operand of 
this instruction defines the appropriate offset location 
within the desired FDB. 
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3.2 OPNS$X - OPEN FILE FOR SHARED ACCESS 


The OPNSS$x macro opens a file for shared access. This macro has’ the 
same format, that is, takes the same alphabetic suffixes and run-time 
parameters, as the generalized OPENS$x macro. The shared access 
conditions that result from the use of this macro are summarized in 
Section 1.8. 


3.3  OPNTS$W -— CREATE AND OPEN TEMPORARY FILE 


The OPNTSW macro creates and opens a temporary file for some _ special 
purpose of limited duration. If a temporary file is to be used only 
once, it is best created through the OPNTSD macro described in the 
following section. 


The OPNTSW macro creates a file but does not enter a file name _ for 
that file into any associated user directory file. 


In using the OPNTSW macro, you bear the responsibility for marking the 
temporary file for deletion, as described in the procedure in the 
following text. Then, after all operations associated with that file 
are completed, closing the file results in its deallocation. All 
space formerly occupied by the file is then returned for reallocation 
to the pool of available storage on the volume. 


Although the OPNTS$W macro takes the same format and parameters as 
those of the generalized OPENSx macro, the former executes faster 
because no directory entries are made for a temporary file. 


Creating a temporary file is usually done when a program requires a 
file only for the duration of its execution (for example, for use as a 
work file). The general sequence of operations in such instances 
proceeds as follows: 


1. Open a temporary file by issuing the OPNTSW macro. Perform 
any desired operations on that file. If the file is to be 
used only for a single OPNTSW/CLOSES sequence, go to step 6; 
otherwise, continue with step 2. 


2. Before closing the file for processing, save the filename 
block in the associated FDB. The general procedure for 
Saving (and restoring) the filename block is discussed in 
Section 2.5.1. 


3. Close the file by issuing the CLOSES macro (see Section 3.8). 
Continue other processing in the program, as desired. 


4. In anticipation of reopening the temporary file, restore the 
filename block to the FDB by reversing step 2. 


5. Reopen the file by issuing any of the FCS macros that open 


existing files. Resume operations on the file; repeat the 
save, CLOSES, restore, open sequence any desired number of 
times. 


6. Before closing the file the last time, call the .MRKDL 
routine, as shown following, to mark the file for deletion: 


CALL ~-MRKDL 
The .MRKDL routine is described in Section 4.15.1. 


7. Close the file by issuing the CLOSES macro. 
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If the filename block is not saved, the file identification field 


therein is destroyed, because this field is reset to 0 when the file 
is closed. 


Thus, not saving the filename block before closing a temporary file 
results in a "lost" file, because no directory entry is made for a 
temporary file. The usual procedure of listing the volume's directory 
is therefore inapplicable. The only way such a file can be recovered 
is to use the File Structure Verification Utility program (VFY) to 
search the volume's index file. The VFY program has the capability to 
compare the files listed in all the directories on the volume with 
those listed in the index file. If a file appears in the index file, 
but not in a directory, VFY identifies that file for you. This 
program is described in detail in the RSX-11M/M-PLUS Utilities Manual. 


3.4 OPNTS$D - CREATE AND OPEN TEMPORARY FILE AND MARK FOR DELETION 


The OPNTSD macro creates and opens a temporary file. This macro is a 
convenient way to perform the previously shown steps 1 and 6. A file 
marked for deletion cannot be opened by another program. Furthermore, 
when the file is closed, it is deleted from the volume, returning its 
space to the pool of available storage on the volume for reallocation. 


The presumption in issuing the OPNTSD macro is that the file thus 
created is to be used only once. This is a particularly desirable way 
to open a temporary file, because the file will be deleted even if the 
program terminates abnormally without closing the file. 


The OPNTSD macro takes the same format and parameters as those of the 
generalized OPENSx macro. 


NOTE 


If the OPNTSD macro is used for a temporary file 
containing sensitive information, it is recommended 
that you zero the file before closing it, or reformat 
the disk to destroy the sensitive information. 
(Although a temporary file is deleted after use, the 
information physically remains on the volume until 
written over with another file and could be analyzed 
by unauthorized users.) 


3.5 OFIDS$X - OPEN FILE BY FILE ID 


You issue the OFID$x macro to open an existing file using information 
stored in the file identification field (offset location N.FID) of the 
filename block in the FDB (not in your default filename block). Thus, 
issuing this macro invokes an FCS routine that opens a file only by 
file ID (see Section 2.5). The OFIDSx macro, which has the’ same 
format and takes the same parameters as those of the generalized 
OPENSx macro (see Section 3.1), is for use with overlaid programs. 


In describing the functions of the OFIDSx macro, either one of two 
assumptions may apply, as follows: 


e That the necessary context for opening the file has been saved 
from a previous OPENSx operation and restored to the filename 
block in anticipation of opening that file by file ID. Saving 
and restoring the filename block are discussed in detail in 
Section 2.5.1. 
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e That the desired file is to be opened for the first time. In 
that case, the necessary context for opening the file must 
first be stored in the filename block before the OFIDS macro 
can be issued. 


In most cases, the latter assumption applies, requiring that the 
following procedures be performed: 


l. Call the .PARSE routine (see Section 4.7.1). This routine 
takes information from a specified dataset descriptor or 
default filename block, or both, and initializes and fills in 
the specified filename block. 


2. Call the .FIND routine (see Section 4.8.1). This routine 
locates an appropriate directory entry for the file (by file 
name) and stores the file identification information found 
there in the 6-byte file identification field of the filename 
block, starting at offset location N.FID. As a result of 
steps 1 and 2, the necessary context then exists in the 
associated filename block for opening the file by file ID. 


3. Issue the OFIDSx macro. 


The advantage in using the .PARSE and .FIND routines with the OFIDSx 
macro is that you can overlay the program, placing .PARSE and .FIND on 
one branch, and the code for OFIDSx on another branch. This overlay 
structure reduces the program's overall memory requirements. 


Unlike the other FCS macros for opening files, the OFIDSx macro 
requires a nonzero value in the first word of the file identification 
field (N.FID) to work properly. When this field contains a nonzero 
value, FCS assumes that the remaining context necessary for opening 
that file is present and, accordingly, opens the file by file ID. 


Opening an existing file by file ID for write access is a_ special 
case. Because it is intended to rewrite the existing file, the 
following occur: 


e Any initial allocation (F.CNTG) is ignored. 


e File access byte (F.FACC) value NA.NSP (do not supersede file) 
is ignored. 


e File access byte (F.FACC) value FA.CRE (create new file) is 
set even though the file is being rewritten rather than 
created. 


e This operation may not be performed on ANSI magnetic tape. 
The data in the file header labels is not changed when the 


file is written. See Section 5.2 for information on 
positioning file on tape to rewrite a file in a particular 
position. 


The OFIDSW macro is equivalent to the OFIDSU macro. Invoking either 
OFIDSW or OFIDSU opens an existing file by file ID number for update 
and extension. 


3.6 OFNB$X OPEN FILE BY FILENAME BLOCK 


The OFNB$x macro either opens an existing file or creates and opens a 
new file using file name information in the filename block. Like the 
OFIDSx macro previously described, the OFNBSx call is for use with 
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overlaid programs. However, the OFNBSx macro differs in two important 
respects: it can be issued to create a new file, and it can be issued 
to open a file by filename block. 


The OFNBSx call has the same format and takes the same parameters as 
those of the generalized OPENSx macro (as described in Section 3.1.1): 


OFNBSx fdb,lun,dspt,racc,urba,urbs,err 


The OFNBSx macro also uses the same suffixes that are available to the 
OPENSx macro: OFNBSR, OFNBSW, OFNBSM, OFNBSU, OFNBSA. The suffixes 
have the same meaning as they do for OPENSx (see Table 3-1). 


In describing the functions of the OFNBS$x macro, the same assumptions 
outlined for OFID$x apply, namely, that the filename block has been 
saved and restored in anticipation of issuing the OFNBSx macro, or 
that the file is being opened for the first time. Because the 
procedures for saving and restoring the filename block are detailed in 
Section 2.5.1, the following discussion assumes that the desired file 
is being opened for the first time. In this case, the filename block 
in the FDB must be initialized, as described in the following text. 


To open a file by filename block, the following information must be 
present in the filename block of the associated FDB: 


1. The file name (offset location N.FNAM) 

2. The file type or extension (offset location N.FTYP) 
3. The file version number (offset location N.FVER) 

4. The directory ID (offset location N.DID) 

5. The device name (offset location N.DVNM) 

6. The unit number (offset location N.UNIT) 


In providing the information to the filename block, you can use either 
of two general procedures, as described in the following sections. 


3.6.1 Dataset Descriptor or Default Filename Block 


If the dataset descriptor contains all the required information listed 
previously, follow these procedures: 


1. Call the .PARSE routine (see Section 4.7.1). This routine 
takes information from a specified dataset descriptor and 
default filename block, or both, and fills in the appropriate 
offsets of a specified filename block. 


2. Issue the OFNBSx macro. 


3.6.2 Default Filename Block Only 


If a default filename block is to be used in providing the required 
information to FCS, follow these procedures: 


1. Issue the NMBLKS macro (see Section 2.4.2) to create and 
initialize a default filename block. With the exception of 
the directory ID, this structure provides all the requisite 
information to FCS. 
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2. To provide the directory ID, call either of the following 
routines: 


- Call the .GTDIR routine (see Section 4.9.1) to retrieve 
the directory ID from the specified dataset descriptor and 
to store the directory ID in the default filename block. 


- Call the .GTDID routine (see Section 4.9.2) to retrieve 
the default UIC from SSFSR2 and to store the directory ID 
in the default filename block. 


3. Move the entire default filename block manually into the 
filename block associated with the file being opened. 


4. Issue the OFNBSx macro. 


Note that the coding for OFNBSx operations normally resides in an 
overlay apart from that containing the other FCS routines identified 
previously. 


Issuing the OFNBS$x macro is usually done under the premise that the 
filename block contains the requisite information, as described 
previously. However, if the file identification field (offset 
location N.FID) in the filename block contains a nonzero value when 
the call to OFNBSx is issued, the file is unconditionally opened by 
file ID. 


If you expect to open both new and existing files, and memory 
conservation is an objective, the OFNBSx macro is most suitable for 
opening such files. The OFIDSx coding should not be included in the 
same overlay with OFNBSx, because OFIDSx overlaps the function of 
OFNBSx and, therefore, needlessly consumes memory space. 


3.7 OPENS - GENERALIZED OPEN FOR SPECIFYING FILE ACCESS 


Usually, when you want to create a file, the file name and the file 
type are specified, and FCS is allowed to assign the next higher file 
version number. However, if the OPENSW macro is issued for a file 
having an explicit file name, file type, and file version number, and 
a file of that description already exists in the specified UFD, the 
old file is superseded. 


By issuing the OPENS macro without an alphabetic suffix, and by 
specifying two additional parameters, you can inhibit the superseding 
of a file when a duplicate file specification is encountered in the 
UFD. Rather than deleting the old version of the file, an error 
indication (IE.DUP) is returned to offset location F.ERR of the 
applicable FDB. 


All parameters of this macro are identical to those specified for the 
generalized OPENSx macro (see Section 3.1), with the exception of the 
facc parameter and the dfnb parameter. These additional parameters 
are described in this section. 


Format 


OPENS fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err 
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Parameter 
facc 


Any one or an appropriate combination of the following symbolic 
values indicating how the specified file is to be accessed: 


e FO.RD - Requests that an existing file is to be opened for 
reading only. 


e FO.WRT - Requests that a new file is to be created and opened 
for writing. 


e FO.APD - Requests that an existing file is to be opened and 
appended. 


e FO.MFY - Requests that an existing file is to be opened and 
modified. 


e FO.UPD - Requests that an existing file is to be opened, 
updated, and, if necessary, extended. 


e FA.NSP - Requests, in combination with FO.WRT, that the old 
file having the same file specification is not to be 
superseded by the new file. 


@ FA.TMP - Requests, in combination with FO.WRT, that the file 
is to be a temporary file. 


@e FA.SHR - Requests that the file is to be opened for. shared 
access. 


dfnb 


The symbolic address of the default filename block. This 
parameter is the same as that described in connection with the 
FDOPSA/FDOPSR macro. 


The previously described parameters initialize FDB offset locations 
F.FACC and F.DFNB with appropriate values. 


Any logically consistent combination of the previously described file 
access symbols is permissible. The particular combination required to 
create and write a new file without superseding an existing file 
follows: 

OPENS #OUTFDB, #FO.WRT! FA.NSP 
The following macro creates a temporary file for shared access: 


OPENS #OUTFDB, #FO.WRT!FA.TMP!FA.SHR 


NOTE 


You can use RO only to pass the FDB address parameter. 
Any other use of RO when you issue the OPENS macro 
will fail. 
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3.8 CLOSE$ - CLOSE SPECIFIED FILE 


When the processing of a file is completed, you must close it by 
issuing the CLOSES macro. The CLOSES operation performs the following 
housekeeping functions: 


1. Waits for all I/O operations in progress for the file to be 
completed (multiple-buffered record I/0 only) 


2. Ensures that the FSR block buffer, which contains data for an 
output file, is completely written if it is partially filled 
(record I/0 only) 

3. By default, truncates the file being closed 


4. Deaccesses the file 


5. Releases the FSR block buffer(s) allocated for the file 
(record I/O only) 


6. Prepares the FDB for subsequent use by clearing appropriate 
FDB offset locations 


7. Calls an optional user-coded and user-specified 
error-handling routine if an error condition is detected 
during the CLOSES operation 

Note that I/O does occur in items 1 and 2. Therefore, your program 
should include error processing for CLOSES calls as it would for calls 
to PUTS. 


Issuing a CLOSES when a file is already closed results in a success 
Status code. Closing a file that is already closed is not an error. 


3.8.1 Format of CLOSES Macro 
Format 
CLOSES fdb,err 
Parameter 
fdb 
A symbolic value of the address of the associated FDB. 
err 


The symbolic address of a user-coded, optional error-handling 
routine. 


The following examples illustrate the use of the CLOSES macro: 

CLOSES #FDBIN,CLSERR 

CLOSES ,CLSERR 

CLOSES RO 
The first example shows an explicit declaration for the relevant FDB, 
and the symbolic address of a user-coded error-handling routine to be 
entered if the CLOSES operation is not completed successfully. The 


last two examples assume that RO currently contains the address of the 
appropriate FDB. 
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3.9 GETS - READ LOGICAL RECORD 


The GET$ macro reads logical records from ae file. After a GETS 
operation, the next record buffer descriptors in the FDB always 
identify the record just read; that is, offset location F.NRBD+2 
contains the address of the record just read, and offset location 
F.NRBD contains the size of that record (in bytes). This is true of 
GETS operations in both move and locate mode. 


In move mode, a GETS operation moves a record to your task's' record 
buffer (as defined by the current contents of F.URBD+2 and F.URBD), 
and the address and size of that record are then returned to the next 
record buffer descriptors in the FDB (F.NRBD+2 and F.NRBD). 


In locate mode, if the entire record resides within the FSR block 
buffer, then the address and the size of the record just read are 
returned to the next record buffer descriptors (F.NRBD+2 and F.NRBD). 
If, on the other hand, the entire record does not reside within the 
FSR block buffer, then that record is moved piecemeal into your task's 
record buffer, and the address of your task's record buffer and the 
size of the record are returned to offset locations F.NRBD+2 and 
F.NRBD, respectively. 


After returning from a GETS operation in locate mode, regardless of 
whether moving the record was necessary, F.NRBD+2 always contains the 
address of the record just read, and F.NRBD always contains the size 
of that record. 

If the record read was a sequenced record, the sequence number is 
stored in F.SEQN regardless of whether the GET$ was in move mode or 
locate mode. 


GET$ operations are fully synchronous; that is, record I/O operations 
are completed before control is returned to your program. 


Specific FDB requirements for GETS$ operations are presented in Section 
3. 96-25 


3.9.1 Format of GETS Macro 
Format 
GETS fdb,urba,urbs,err 
Parameter 
fdb 
A symbolic value of the address of the associated FDB. 
urba 
The symbolic address of your task's record buffer that is to be 
used for record I/O operations in move or locate mode. When 


specified, this parameter initializes FDB offset location 
F.URBD+2. 
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urbs 
A numeric value defining the size (in bytes) of your task's 
record buffer. This parameter determines the largest record that 
can be placed in your task's record buffer in move or _ locate 
mode. When specified, this parameter initializes offset location 
F.URBD in the associated FDB. 

err 


The symbolic address of an optional error-handling routine, which 
you coded. 


If neither the urba nor the urbs parameter is specified in the GETS 
macro, FCS assumes that these requisite values have been supplied 
previously through the FDRCSA, the FDRCSR, or the generalized OPENSx 
macro. Any resulting nonzero values in offset locations F.URBD+2 and 
F.URBD are used as the address and the length, respectively, of your 
task's record buffer. 


If either of the following conditions occurs during record I/0 
operations, FCS returns an error indication (IE.RBG) to offset 
location F.ERR of the FDB, indicating an illegal record size: 


e In move mode, the record size exceeds the limit specified in 
offset location F.URBD. 


e In locate mode, the record size exceeds the limit specified in 
offset location F.URBD, and the record must be moved because 
it crosses block boundaries. 


In both move and locate mode, only data up to the amount specified in 
F.URBD is placed in your task's buffer. The next GETS begins reading 
at the beginning of the next record. 


The following statements show how the GETS macro may be used in a 
program: 


GETS RO,,,ERROR 


In this example, the address of the desired FDB is assumed to be 
present in RO. Note that the next two parameters, that is, your 
task's record buffer address (urba) and your task's record buffer size 
(urbs), are null. In this case, FCS assumes that the appropriate 
values for FDB offset locations F.URBD+2 and F.URBD, respectively, 
have been specified previously in the FDRCSA, the FDRCSR, or the 
generalized OPENSx macro. The final parameter in the string is’ the 
symbolic address of a user-coded error-handling routine. 


GETS , #RECBUF, #25. ,ERROR 


This example also assumes that RO contains the address of the desired 


FDB. Explicit parameters then define the address and the size, 
respectively, of your task's record buffer and an error handler, which 
you coded. 


GETS #INFDB 


This example shows a GETS macro in which only the address of the FDB 
is specified. 


NOTE 


You can use RO only to pass the FDB_ address. Any 
other use of RO when you issue the GETS macro will 
fail. 
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3.9.2 The FDB Relevant to GETS Operations 


The following sections summarize the essential aspects of GETS 
operations in move and locate mode with respect to the associated FDB. 


The following text focuses mainly on whether your task's record buffer 
is required under certain conditions. In this regard, you should 
recall that your task's record buffer descriptors, that is, the urba 
and the urbs parameters, may be specified in the FDRCSA, the FDRCSR, 
or the generalized OPENSx macro, as well as the I/0O-initiating GETS 
macro. These parameters must be present in the GETS macro (to 
appropriately initialize the FDB) only if they were not previously 
supplied through other available means. 


If operating in random access mode, the number of the record to be 
read is maintained by FCS in offset locations F.RCNM and F.RCNM+2 of 
the associated FDB. FCS increments this value after each GETS or 
GETSR operation to point to the next record in the FSR block buffer. 


Thus, unless your task alters the values in locations F.RCNM and 
F.RCNM+2 before each issuance of the GETS or GETSR macro call, the 
next record in sequence is read. Your specified record buffer size 
(that is, the urbs parameter) always determines the largest record 
that can be read during a GETS operation. 


3.9.2.1 GET$ Operations in Move Mode - With respect to GETS 
operations in move mode (refer to Section 1.7.1.1 for information on 
move mode), the following generalization applies. If records are 
always moved to the same record buffer in your task, the urba and urbs 
Parameters need be specified only in the initial GETS macro. 
Alternatively, these values may be specified beforehand through any 
available means identified previously, for initializing your task's 
record buffer descriptor cells in the FDB. In any case, offset 
locations F.URBD+2 and F.URBD remain appropriately initialized for all 
subsequent GETS operations in move mode that involve the same record 
buffer in your task. 


3.9.2.2 GET$ Operations in Locate Mode - In performing GETS 
operations in locate mode (refer to Section 1.7.1.2 for information on 
locate mode), you should take into account the following: 


NOTE 


In the following text, reference is made to the FSR 
block buffer. By default, the blocksize that FCS uses 
is equivalent to the buffer size of the device on 
which the file is opened. If big buffering is enabled 
(that is, an ovbs parameter value is specified in the 
FDBF$x macro as described in Section 2.2.1.6), the FSR 
block buffer will be more than one block long. AS a 
result, it may not be necessary to move a record even 
though it crosses block boundaries, because both 
blocks are currently within the FSR block buffer 
space. Thus, moves are only necessary when the record 
crosses a buffer boundary, which is not necessarily 
the same as a block boundary in a big-buffered file. 
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e If fixed-length records are to be processed, and if they fit 
evenly within the FSR block buffer, your task's record buffer 
descriptors need not be present in the associated FDB. 


e If fixed-length records that do not fit evenly within the FSR 
block buffer are to be processed, or if variable-length 
records are to be processed, your task's record buffer 
descriptors need not be present in the FDB, provided that the 
file being processed exhibits the attribute of records not 
being allowed to cross block boundaries (FD.BLK). 


The property of records not crossing block boundaries is 
established as the file is created. Specifically, if offset 
location F.RATT in the FDB is initialized with FD.BLK prior to 
the time the file is created, the records in the resulting 
file are not allowed to cross buffer boundaries. 


For an existing file, the file attribute section of the file 
header block is read when the file is opened; thus, all 
attributes of that file are made known to FCS, including 
whether records within that file are allowed to cross block 
boundaries. 


The design of FCS requires you to use your task's' record 
buffer only in the event that records (either fixed or 
variable in length) cross buffer boundaries. 


e If a GETS operation is performed in locate mode, and_ the 
record is contained entirely within the FSR block buffer, the 
address of the record within the FSR block buffer and the size 
of that record are returned to the associated FDB in offset 
locations F.NRBD+2 and F.NRBD, respectively. However, if that 
record crosses buffer boundaries, it is moved to your task's 
record buffer. In this case, the address of your task's 
record buffer and the size of the record are returned to 
offset locations F.NRBD+2 and F.NRBD, respectively. 


In summary, if the potential exists for crossing buffer boundaries 
during GETS operations in locate mode, then your task's record buffer 
descriptors must be supplied through any available means to 
appropriately initialize offset locations F.URBD+2 and F.URBD in the 
associated FDB. 


3.10 GETS$R - READ LOGICAL RECORD IN RANDOM MODE 


The GETSR macro reads fixed-length records from a file in random mode. 
Thus, by definition, issuing this macro requires that you be familiar 
with the structure of the file to be read and, furthermore, that you 
be able to specify precisely the number of the record to be read. 


The GETS and GETSR macros are identical, except that the parameter 
list of GETSR includes the specification of the desired record number. 
If the desired record number is already present in the FDB (at offset 
locations F.RCNM and F.RCNM+2), then GETS may be used. If, however, 
the record access byte in the FDB (offset location F.RACC) has not 
been initialized for random access operations with FD.RAN in the 
FDRCSA, the FDRCSR, or the generalized OPENSx macro, then neither GETS 
nor GETSR will read the desired record. 


The GETSR macro takes two more parameters in addition to those 
specified in the GETS macro. 
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Format 

GETSR fdb,urba,urbs,lrcnm,hrenm,err 
Parameter 
lrcnm 


A numeric value specifying the low-order 16 bits of the number of 
the record to be read. This value, which must be specified, is 
stored in offset location F.RCNM+2 in the FDB. The GETSR_ macro 
call seldom requires more than 16 bits to express the record 
number. A logical record number up to 65,536(decimal) may be 
specified through this parameter. If this parameter is not 
sufficient to completely express the magnitude of the record 
number, the following parameter must also be specified. 


hrenm 


A numeric value specifying the high-order 15 bits of the number 
of the record to be read. This value is stored in FDB offset 
location F.RCNM. If specified, the combination of this parameter 
and the Ilrcnm parameter determines the number of the desired 
record. Thus, an unsigned value having a total of 31 bits of 
Magnitude may be used in defining the record number. 


If this parameter is not specified, offset location F.RCNM 
retains its initialized value of 0. 


If you use F.RCNM to specify a desired record number for any 
given GETSR operation, this cell must be cleared before issuing a 
subsequent GETSR macro that requires 16 bits or less to express 
the desired record number; otherwise, any residual value in 
F.RCNM yields an incorrect record number. 


If the lrenm and hrenm parameters are not specified in a subsequent 
GETSR macro, the next sequential record is read because the record 
number in offset locations F.RCNM+2 and F.RCNM is increased by one 
with each GETS operation. In the case of the first GETSR, after 
opening the file, record number 1 is read because the record number 
has been initialized to 0 by the OPEN. If a record other than the 
next sequential record is to be read, you must explicitly specify the 
number of the desired record. 


The following statements represent the use of the GETSR macro: 
GETSR #INFDB, #RECBUF, #160.,#1040.,,ERROR 


In this example the number of the desired record to be read, that is, 
1040(decimal), is expressed through the first of two available fields 
for this purpose; the second field is not required and is therefore 
reflected as a null specification. 


GETSR #FDBADR, #RECBUF, #160. ,R3 


This example reflects the use of general register 3 in specifying the 
logical record number. This register, or any other location so used, 
must be preset with the desired record number before issuing the GETSR 
macro. 


NOTE 


RO can be used only to pass the FDB address parameter. 
Any other use of RO when issuing the GETSR macro will 
fail. 
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3.11 GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE 


The GETSS macro reads logical records from a file in sequential mode. 
Although the routine invoked by the GETSS macro requires less memory 
than that invoked by GETS (see Section 3.9), GETSS has the same format 
and takes the same parameters. The GETSS macro is specifically for 
use in an overlaid environment in which the amount of memory available 
to the program is limited and files are to be read in strictly 
sequential mode. 


If both GETSS and PUTSS are to be used by the program, note that the 
savings in memory usage over GETS and PUTS can be realized only if 
GETSS and PUTSS are placed on different branches of the overlay 
structure. 


3.12 PUT$ - WRITE LOGICAL RECORD 


The PUTS macro writes logical records to a file. If operating in 
random access mode, the number of the record to. be written is 
maintained by FCS in offset locations F.RCNM and F.RCNM+2 of the 
associated FDB. FCS increases this value by one after each PUTS or 
PUTSR operation to point to the next sequential record position. 
Thus, unless your program alters this value before issuing another 
PUTS or PUTSR operation, the next record in sequence is written. 


For PUTS operations, offset locations F.NRBD+2 and F.NRBD in the 
associated FDB must contain the address and the size, respectively, of 
the record to be written. The distinction between move mode _ and 
locate mode for PUTS operations relates to the building or the 
assembling of the data into a record. Specifically, in move mode the 
record is built in a buffer of your choice. This buffer is not 
necessarily your task's record buffer previously described in the 
context of record I/O operations. In other words, you can build 
records in an area of a program apart from that normally defined by 
your task's record buffer descriptors in the FDB (F.URBD+2 and 
F.URBD). In this case, you specify the address of the record buffer 
so used and the size of the record in the PUTS macro, and the record 
thus built is then moved into the FSR block buffer. 


In locate mode, however, the record is built at the address specified 
by the contents of offset location F.NRBD+2, and only the record size 
need be specified in the PUTS macro. Then, if the record so built is 
not already in the FSR block buffer, it is moved there as the PUTS 
operation is performed. 


If the records in the file are sequenced records, the field F.SEQN in 
the FDB contains the sequence value, which you can modify. 


PUTS operations are fully synchronous; that is, record I/O operations 
are completed before control is returned to your task's program. 


A random PUTS operation in locate mode requires the use of the .POSRC 
routine. This operation is described in detail in Section 4.9.2. 


Specific FDB requirements for PUTS operations are presented in Section 
Sel 2e2. 


3.12.1 Format of PUTS Macro 
Format 


PUTS fdb,nrba,nrbs,err 
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Parameter 
fdb 


A symbolic value of the address of the associated FDB. 


nrba 
The symbolic address of the next record buffer, that is, the 
address of the record to be PUTS. This parameter initializes FDB 
offset location F.NRBD+2. 

nrbs 
A numeric value specifying the size of the next record buffer, 
that is, the length of the record to be PUTS. This parameter 
initializes FDB offset location F.NRBD. 

err 


The symbolic address of an optional error-handling routine, which 
you coded. 


The following examples show how the PUT$ macro may be used in a 
program: 


PUTS #FDBADR,,,ERRRT 


In this example the next record buffer address (nrba parameter) and 
the next record buffer size (nrbs parameter) are null. These null 
specifications imply that the current values in offset locations 
F.NRBD+2 and F.NRBD of the associated FDB are suitable to the current 
operation. Note also that fixed-length records could also be written 
in locate mode by issuing this macro. 


PUTS 17 #160.,ERRRT 


This example contains null specifications in the first two parameter 
fields, assuming that RO currently contains the address of the 
associated FDB and that variable-length records are to be written to 
the file. 


PUTS RO 


This example specifies only the address of the FDB; all other 
parameter fields are null. 


NOTE 


RO can only be used to pass the FDB address parameter 
as shown in the previous example; it cannot be used to 
pass any other parameter in the PUTS macro. 


3.12.2 The FDB Relevant to PUTS Operations 


This subsection highlights aspects of PUTS operations in move and 
locate mode that have a bearing on the associated FDB. 


The conditions under which your task's record buffer is or is not used 
are summarized. As is the case for GETS operations, if your task's 
record buffer is required for PUTS operations, the buffer descriptors 


FILE-PROCESSING MACROS 


(that is, the urba and urbs parameters) may be supplied to the 
associated FDB through the FDRCSA, the FDRCSR, or the generalized 
OPENSx macro. In any case, offset locations F.URBD+2 and F.URBD must 
be appropriately initialized if PUTS operations require the 
utilization of your task's record buffer. Note, however, that PUTS 
operations in move mode never require a record buffer. 


If your task's record buffer is required, the specified size of that 
buffer (that is, the urbs parameter) always determines the size of the 
largest record that can be written to the specified file. 


Whether in move or locate mode, a PUTS operation uses the information 
in offset locations F.NRBD+2 and F.NRBD, that is, the next record 
buffer descriptors, to determine whether the record must be moved into 
the FSR block buffer. In the event that the record does have to be 
moved, and the size of that record is such that it cannot fit in the 
space remaining in the FSR block buffer, one of two possible 
operations is performed: 


e If records are allowed to cross block boundaries, then’ the 
first part of the record is moved into the FSR block buffer, 
thereby completing a virtual block. That block buffer is then 
written out to the volume, and the remaining portion of the 
record is moved into the beginning of the next FSR block 
buffer. 


e If records are not allowed to cross block boundaries (because 
of the file attribute FD.BLK specified in the associated FDB), 
then the FSR block buffer is written out to the volume as is, 
and the entire record is moved into the beginning of the next 
FSR block buffer. 


3.12.2.1 PUT$ Operations in Move Mode - A PUTS operation in move mode 
(see Section 2.2) is basically driven by specifying in each PUTS macro 
the address and the size of the record to be written. Then, as_ the 
PUTS operation is performed, FCS moves the record into the appropriate 
area of the FSR block buffer. 


In summary, the following generalizations apply for PUTS operations in 
move mode: 


e Your task's record buffer descriptors need not be present in 
the FDB because the programmer is dynamically specifying the 
address and the length of the record to be written at each 
issuance of a PUTS macro. The values so specified dynamically 
update offset locations F.NRBD+2 and F.NRBD in the associated 
FDB. 


e If the file consists of fixed-length records, then the 
generalized OPENSx macro (see Section 3.1) initializes offset 
location F.NRBD with the appropriate record size, as defined 
by the contents of offset location F.RSIZ. Thus, the size of 
the record need not be specified as the nrbs parameter in any 
PUTS macro involving this file. 


e If variable-length records are being PUTS, the size of each 
record must be specified as the nrbs parameter in each PUTS 
Macro call involving this file, thus setting offset location 
F.NRBD to the appropriate record size. 
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3.12.2.2 PUT$ Operations in Locate Mode - Basically, your  task's 
record buffer is required for PUTS operations in locate mode (see 
Section 2.2) only when the potential exists for records to cross 
buffer boundaries. In other words, if there is insufficient space in 
the FSR block buffer to accommodate the building of the next record, 
you must provide a buffer in your task's memory space to build that 
record. 


When a file is initially opened for PUTS operations in locate mode, 
FCS sets up offset location F.NRBD+2 to point to the area in the FSR 
block buffer where the next record is to be built. Then, each PUTS 
operation thereafter in locate mode updates the address value in this 
cell to point to the area in the FSR block buffer where the next 
record is to be built. Thus, after each PUTS operation in locate 
mode, F.NRBD+2 points to the area where the next record is to be 
built. This logic dictates whether your record buffer is required in 
locate mode. 


In this regard, the following generalizations apply: 


NOTE 


In the following discussion, reference is made to the 
FSR block buffer. By default, the block size that FCS 
uses is equivalent to the buffer size of the device on 
which the file is opened. If big buffering is enabled 
(that is, an ovbs parameter value is specified in the 
FDBFSx macro, as described in Section 2.2.1.6) the FSR 
block buffer will be more than one block long. As a 
result, it may not be necessary to move a record even 
though it crosses block boundaries, because both 
blocks are currently within the FSR_ block buffer 
space. Thus, moves are only necessary when the record 
crosses a buffer boundary, which is not necessarily 
the same as a block boundary in a big-buffered file. 


e If fixed-length records are being PUTS and they fit evenly 
within the FSR block buffer, your task's record buffer is not 
required. 


e If a fixed-length record crosses block boundaries, your task's 
record buffer descriptors must be present in offset locations 
F.URBD+2 and F.URBD of the associated FDB. In this case, 
after determining that the record cannot fit in the FSR block 
buffer, FCS sets offset location F.NRBD+2 to point to your 
task's record buffer. Then, when the record is PUTS, it is 
moved from your record buffer to the FSR block buffer. 


e If a variable-length record is being PUTS, the potential 
task's record buffer descriptors must be present in offset 
exists for crossing block boundaries. In this case, your 
task's record buffer descriptors must be present in offset 
locations F.URBD+2 and F.URBD of the associated FDB. 
Moreover, the size of each variable-length record must be 
specified as the nrbs parameter in each PUTS macro. 


Determining if FCS points offset location F.NRBD+2 to the FSR 
block buffer for the PUTS operation or to your task's record 
buffer is based on whether there is potentially enough room in 
the FSR block buffer to accommodate the record. 
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Because the records are variable in length, it must be assumed 
that the largest possible record is PUTS, as defined by the 
size of your task's record (F.URBD). Thus, if a record of 
this defined size cannot fit in the space remaining in the FSR 
block buffer, FCS sets offset location F.NRBD+2 to point’ to 
your task's record buffer. 


Each PUTS operation in locate mode sets up the FDB for the next PUTS. 
In other words, the specified record size is used by FCS as the 
worst-case condition in determining whether sufficient space exists in 
the FSR to build the next record. 


If variable-length records are being processed that are shorter than 
the largest defined record size, FCS may move records unnecessarily 
from your task's record buffer to the FSR block buffer. For example, 
assume that your task has allocated a 132-byte record buffer. Assume 
further that the available remaining space in the FSR block buffer is 
less than 132 xbytes. In this case, FCS continues to point to your 
task's record buffer for PUTS operations, even if you continue to PUTS 
short (10- or 20-byte) records. Thus, some unavoidable movement of 
records takes place in locate mode. 


If the largest record that you intend to PUTS is 80 bytes, for 
example, then the largest defined record size should not be specified 
as 132 bytes (or any length larger than that intended to be PUTS). 
Aside from having to allocate a smaller record buffer in your task, 
PUTS operations in locate mode are more efficient if this precaution 
is observed. Exercising care in this regard reduces the tendency to 
move records from your task's record buffer to the FSR block buffer 
when they might otherwise be built directly in the FSR block buffer. 


3.13 PUTSR - WRITE LOGICAL RECORD IN RANDOM MODE 


The PUTSR macro writes fixed-length records to a file in random mode. 
As noted in Section 3.10 in discussing the GETSR macro, operations in 
random access mode require you to be very familiar with the contents 
of such files. The PUTSR macro also relies entirely on you to specify 
the number of the record before a specified PUTS operation can be 
performed. Because the usual purpose of a PUTSR operation is to 
update known records ina file, it is assumed that you also know the 
number of such records within the file. 


The PUTS and PUTSR macros are identical, except that PUTSR allows’ the 
specification of the desired record number. If the desired record 
number is already present in the FDB (at offset locations F.RCNM and 
F.RCNM+2), then PUTS and PUTSR may be used interchangeably. However, 
if the record access byte in the FDB (offset location F.RACC) has not 
been initialized for random access operations with FD.RAN in the 
FDRCSA, the FDRCSR, or the generalized OPENSx macros, then neither 
PUTS nor PUTSR will write the desired record. 


The PUTSR macro takes two more parameters in addition to those 
specified in the PUTS macro. 


Format 


PUTSR fdb,nrba,nrbs,lrcnm,hrcnm,err 
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Parameter 
lrenm 


A numeric value specifying the low-order 16 bits of the number of 
the record to be processed. This parameter serves the same 
purpose as the corresponding parameter in the GETSR macro (see 
Section 3.10), except that it identifies the record to be 
written. 


hrcenm 


A numeric value specifying the high-order 15 bits of the number 
of the record to be processed. This parameter serves the same 
purpose as the corresponding parameter in the GETSR macro, except 
that it identifies the record to be written. 


If this parameter is not specified, offset location F.RCNM 
retains its initialized value of 0. 


If F.RCNM is used in expressing a desired record number for any 
given PUTSR operation, you must clear this cell before issuing a 
subsequent PUTSR macro that requires 16 bits or less in 
expressing the desired record number; otherwise, any residual 
value in F.RCNM results in an incorrect record number. 


The lrcnm and hrcnm parameters initialize offset locations F.RCNM+2 
and F.RCNM, respectively, in the associated FDB. If these values are 
not specified in a subsequent PUTSR macro, the next sequential record 
is written, because FCS increases the record number by one in these 
cells after each PUTS operation. In the case of the first PUTSR after 
opening the file, record number 1 is written. Note that this is true 
even if the file has been opened for an append (OPENSA). If a_ record 
other than the next sequential record is to be written, you must 
explicitly specify the number of the desired record. 


NOTE 


A random mode PUTSR operation executed in locate mode 
must be preceded by a call to .POSRC. Because locate 
mode allows you to store data directly into the block 
buffer, the file must be positioned so that the 
desired record position is in fact in the block 
buffer. See Section 4.10.2 for further details. 


Examples of how the PUTSR macro may be used in a program follow: 
PUTSR #OUTFDB, #RECBUF, ,#12040.,,ERRLOC 


In the first example, the presence of RECBUF as the next record buffer 
address (nrba) parameter merely indicates that you are specifying the 
address of the record. Although specifying this address repeatedly is 
unnecessary, it is not invalid. Normally, a buffer address is 
specified dynamically, because other PUTS macro calls may be 
referencing different areas in memory; thus, the address of the record 
must be explicitly specified in each PUTS macro. Note also that the 
next record buffer size (nrbs) parameter is null, because this 
Parameter is required only in the case of writing variable-length 
records. Also, the second of the two available parameters for 
defining the record number is null. 


PUTSR #FDBADR, #RECBUF, ,R4 


PUTSR #FDBADR, #RECBUF,,LRN 
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Note in the second and third examples that R4 and a memory location 
(LRN) are used to specify the logical record number. Such a 
specification assumes that you have preset the desired record number 
in the referenced location. 


NOTE 


You can use RO only to pass the FDB address. Any 
other use of RO when you issue the PUTSR macro will 
fail. 


3.14 PUT$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE 


The PUTSS macro writes logical records to a file in sequential mode. 
Although the routine invoked by the PUTSS macro requires less memory 
than that invoked by PUTS (see Section 3.12), PUTSS has the same 
format and takes the same parameters. The PUTSS macro is specifically 
for use in an overlaid environment in which the amount of memory 
available to the program is limited and files are to be written in 
strictly sequential mode. 


If both GETSS and PUTSS are to be used by the program, the savings in 
memory utilization over GETS and PUTS are realized only if GETSS and 
PUTSS are placed on different branches of the overlay structure. 


3.15 READS - READ VIRTUAL BLOCK 


The READS macro reads a virtual block of data from a _ block-oriented 
device (for example, a magnetic tape, a disk, or DECtape). In 
addition, if certain optional parameters are specified in the READS 
macro, status information is returned to the I/O status block (see 
Section 2.8.2), or the program traps to an AST service routine, which 
you coded, at the completion of block I/O operations (see Section 
228.3) 


In issuing the READS (or WRITES) macro, you are responsible for 
synchronizing all block I/0 operations. For this reason, the WAITS 
macro is provided (see Section 3.17), allowing you to suspend program 
execution until a specified READS or WRITES operation has been 
completed. It is important, however, that you test the contents of 
F.ERR in the FDB for error codes immediately after issuing the READS 
or WRITES call as well as on return from the WAITS call. When errors 
occur during multiple-block transfers, the second word of the I/0 
status block will contain the number of bytes transferred before the 
error occurred. The READS or WRITE operations can return error codes 
distinct from those that can be present on completing a WAITS 
operation. For example, IE.EOF will be returned upon completing the 
READS operation, but not upon completing WAITS. 


When your task issues the WAITS macro with a READS (or WRITES) macro, 
you must ensure that the event flag number and the I/0 status block 
address specified in both macro calls are the same. 


When the WTSES macro waits for I/O completion, the issuing task must 
check I/0 errors by examining the I/O status block (defined by the 
task). (The I/O status block is described in Section 2.8.2.) When 
WTSES is used, FCS will not return a completion code to offset F.ERR 
in the FDB. 
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3.15.1 Format of READS Macro 


From the format following, note that the parameters of the READS macro 
are identical to those of the FDBKSA or the FDBKSR macro, with the 
exception of the fdb and err parameters. Certain FDB parameters may 
be set at assembly time (FDBKSA), initialized at run time (FDBKS$R), or 
set dynamically by the READS macro. In any case, certain information 
must be present in the FDB before the specified READS (or WRITES) 
Operation can be performed. These requirements are noted in Section 
3615.2. 


Format 
READS fdb,bkda,bkds, bkvb,bkef,bkst,bkdn,err 
Parameter 


fdb 


A symbolic value of the address of the associated FDB. 
bkda 


The symbolic address of the block I/O buffer in your program. 
This parameter need not be specified if offset location F.BKDS+2 
has been previously initialized through either the FDBKSA or the 
FDBKSR macro. 


bkds 


A numeric value specifying the size (in bytes) of the virtual 
block to be read. This parameter need not be specified if offset 
location F.BKDS has been previously initialized through either 
the FDBKSA or the FDBKSR macro. In any case, the maximum block 
size that may be specified for file-structured devices is 32256 
bytes. 


bkvb 


The symbolic address of a 2-word block in your program containing 
the number of the virtual block to be read. This parameter 
causes offset locations F.BKVB and F.BKVB+2 to be initialized 
with the virtual block number; F.BKVB+2 contains the low-order 16 
bits of the virtual block number, and F.BKVB contains’ the 
high-order 15 bits. 


As noted in connection with the FDBKSA macro described in Section 
2.2.1.4, assembly-time initialization of the virtual block number 
in the FDB is ineffective, because the generalized OPENSx macro 
sets the virtual block number in the FDB to l. 


The virtual block number can be made available to FCS only 
through the FDBKSR macro or the I/0O-initiating READS (or WRITES) 
macro after the file has been opened. The virtual block number 
is created as described in item 4 of Section 2.2.2.1. 


The READS function checks the specified virtual block number to 
ensure that it does not reference a nonexistent block, that is, a 
block beyond the end of the file. If the virtual block number 
references nonexistent data, an end-of-file (IE.EOF) error 
indication is returned to offset location F.ERR of the associated 
FDB; otherwise, the READS operation proceeds normally. If the 
total number of bytes goes beyond the end of the file, then as 


bkef 


bkst 


bkdn 


err 
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many blocks as exist are read and the byte count of the shortened 
transfer is returned in I/O STATUS+2. No error condition occurs, 
so you must check the count on each READ. An end-of-file 
indication is returned only if no blocks can be read. 


If the virtual block number is not specified through any of the 
available means identified already, sequential operation results 
by default, beginning with virtual block number l. The virtual 
block number is incremented by the number of blocks read after 
each READS operation is performed. 


A numeric value specifying the event flag number to be used _ for 
synchronizing block I/O operations. This event flag number is 
used by FCS to signal the completion of the specified block I/0 
operation. The event flag number, which may also be specified 
in either the FDBKSA or the FDBKSR macro, initializes FDB offset 
location F.BKEF; if so specified, this parameter need not be 
included in the READS (or WRITES) macro. 


If this optional parameter is not specified through any available 
means, event flag 32(decimal) is used by default. The function 
of an event flag is discussed in further detail in Section 2.8.1. 


The symbolic address of the I/O status block in your task (see 
Section 2.8.2). This parameter, which initializes offset 
location F.BKST, is optional. The I/O status block is filled in 
by the system when the requested block I/O transfer is completed, 
indicating the success or failure of the requested operation. 


The address of the I/O status block may also be specified in 
either the FDBKSA or the FDBKSR macro. If the address of this 
2-word structure is not supplied to FCS through any of the 
available means, status information cannot be returned to your 
program. Regardless, the event flag specified through the  bkef 
parameter is set to indicate block I/O completion, but, without 
an I/O status block, your program must assume that the operation 
(for example, READS or WRITES) was successful. 


The symbolic entry point address of an AST service routine (see 
Section 2.8.3). If this parameter is specified, a trap occurs 
upon completion of the specified READS (or WRITES) operation. 
This parameter, which is optional, initializes offset location 
F.BKDN. This address value may also be made available to FCS 
through either the FDBKSA or the FDBKSR macro, and, if so 
specified, need not be present in the READS (or WRITES) macro 
call. 


If the address of an AST service routine is not specified through 
any available means, no AST trap occurs at the completion of 
block I/O operations. 


The symbolic address of an optional error-handling routine, which 
you coded. 


The following examples represent READS macros that may be issued to 
accomplish a variety of operations: 


READS RO 
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This example assumes that RO contains the address of the associated 
FDB. Also, all other required FDB initialization has_ been 
accomplished through either the FDBKSA or the FDBKSR macro call. 


READS #INFDB,¢¢¢¢7772RRLOC 


This example shows an explicit declaration of the associate FDB and 
includes the symbolic address of an error-handling routine, which you 
coded. 


READS RO, #INBUF, #BUFSIZ,,#22.,#IOSADR, #ASTADR, ERRLOC 


In this example RO again contains the address of the associated fFDB. 
The block buffer address and the size of the block are specified next 
in symbolic form. The address of the 2-word block in your program 
containing the virtual block number is not specified, as indicated by 
the additional comma in the parameter string. The event flag number, 
the address of the I/0 status block, and the address of the AST 
service routine then follow in order. Finally, the symbolic address 
of an optional error routine is specified. 


READS #INFDB, #INBUF, #BUFSIZ, #VBNADR 


This example reflects, as the last parameter in the string, the 
symbolic address of the 2-word block in your program containing the 
virtual block number. 


NOTE 


You can use RO only to pass the FDB- address. Any 
other use of RO when you issue the READS macro will 
fail. 


3.15.2 The FDB Relevant to READS Operations 


The READS macro requires that the associated FDB be initialized with 
certain values before it can be issued. You can specify these values 
through either the FDBKSA or the FDBKSR macro, or they may be made 
available to the FDB through the various parameters of the READS 
macro. In any case, the following values must be present in the FDB 
to enable READS operations to be performed: 


1. The block buffer address (in offset location F.BKDS+2) 
2. The block byte count (in offset location F.BKDS) 


3. The virtual block number (in offset locations F.BKVB+2 and 
F .BKVB) 


NOTE 


When either READS or WRITES operations are performed, 
FCS maintains the end-of-file block number field 
(F.EFBK) and clears the first free byte in the last 
block field (F.FFBY) in the FDB. During a READS 
operation, end-of-file is determined by the 
end-of-file block number field in F.EFBK. If desired, 
you can modify F.FFBY before closing the file by using 
the CLOSES macro call. 
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3.16 WRITES - WRITE VIRTUAL BLOCK 


The WRITES macro is issued to write a virtual block of data to a 
block-oriented device (for example, magnetic tape, disk, DECtape, or 
DECtape II). Like the READS macro, if certain optional parameters are 
specified in the WRITES macro, status information is returned to the 
I/O status block (see Section 2./8.2), and, at the completion of the 
I/O transfer, the program traps to an AST service routine that is 
supplied to coordinate asynchronous block I/O operations (see Section 
2.8.3). 


Whether or not you supply the address of an AST service routine and an 
event flag number, or both, you are responsible for synchronizing all 
block I/0 processing. The WAITS! macro can be issued with the WRITES 
macro to suspend program execution until a program-dependent I/0 
transfer has been completed. When the WAITS macro is used for this 
purpose, the event flag number and the I/O status block address in 
both macros must be the same. Again, as with READS operations, you 
should check for an error code immediately following the WRITES macro 
as well as on return from the WAITS macro. 


3.16.1 Format of WRITES Macro 


The WRITES macro takes the same parameters as the READS macro. The 
bkvb parameter represents the’ symbolic address of a 2-word block 
containing the number of the virtual block to be written. The virtual 
block number is incremented after each WRITES operation is performed. 


Format 

WRITES fdb ,bkda,bkds, bkvb, bkef, bkst,bkdn,err 
Parameter 
fdb 

A symbolic value of the address of the associated FDB. 
bkda 3 


The symbolic address of the block I/O buffer in your program. 
This parameter need not be'ispecified if offset location F.BKDS+2 
has been previously initialized through either the FDBKSA or the 
FDBKSR macro. 


bkds 


A numeric value specifying the size (in bytes) of the virtual 
block to be read. This eae need not be specified if offset 
location F.BKDS has been previously initialized through either 
the FDBKSA or the FDBKSR macro. In any case, the maximum block 
size that may be specified for file-structured devices is 32256 
bytes. 


bkvb 


The symbolic address of a 2+word block in your program containing 
the number of the virtual block to be read. This parameter 
causes offset locations P-Bav and F.BKVB+2 to be initialized 
with the virtual block number; F.BKVB+2 contains the low-order 16 
bits of the virtual block number, and F.BKVB contains’ the 
high-order 15 bits. 


bkef 


bkst 


bkdn 
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As noted in connection with the FDBKSA macro described in Section 
2.2.1.4, assembly-time initialization of the virtual block number 
in the FDB is ineffective, because the generalized OPENSx macro 
sets the virtual block number in the FDB to l. 


The virtual block number can be made available to FCS. only 
through the FDBKSR macro or the 1/O0-initiating READS (or WRITES) 
macro after the file has been opened. The virtual block number 
is created as described in item 4 of Section 2.2.2.1. 


The WRITES function checks the specified virtual block number’ to 
ensure that it does not reference a nonexistent block, that is, a 
block beyond the end of the file. If the virtual block number 
references nonexistent data, an end-of-file (IE.EOF) error 
indication is returned to offset location F.ERR of the associated 
FDB; otherwise, the WRITES operation proceeds normally. If the 
total number of bytes goes beyond the end of the file, then as 
many blocks as exist are read and the byte count of the shortened 
transfer is returned in I/O STATUS+2. No error condition occurs, 
so you must check the count on each WRITE. An end-of-file 
indication is returned only if no blocks can be read. 


If the virtual block number is not specified through any of the 
available means identified already, sequential operation results 
by default, beginning with virtual block number l. The virtual 
block number is incremented by the number of blocks read after 
each WRITES operation is performed. 


A numeric value specifying the event flag number to be used _ for 
synchronizing block I/0 operations. This event flag number is 
used by FCS to signal the completion of the specified block I/0 
operation. The event flag number, which may also be specified 
in either the FDBKSA or the FDBKSR macro, initializes FDB offset 
location F.BKEF; if so specified, this parameter need not be 
included in the WRITES macro. 


If this optional parameter is not specified through any available 
means, event flag 32(decimal) is used by default. The function 
of an event flag is discussed in further detail in Section 2.8.1. 


The symbolic address of the I/O status block in your task (see 
Section 228.2) % This parameter, which initializes offset 
location F.BKST, is optional. The I/O status block is filled in 
by the system when the requested block I/O transfer is completed, 
indicating the success or failure of the requested operation. 


The address of the 1/0 status block may also be specified in 
either the FDBKSA or the FDBKSR macro. If the address of this 
2-word structure is not supplied to FCS through any of the 
available means, status information cannot be returned to your 
program. Regardless, the event flag specified through the bkef 
parameter is set to indicate block I/O completion, but, without 
an I/O status block, your program must assume that the WRITES 
operation was successful. 


The symbolic entry point address of an AST service routine (see 
Section 2.8.3). If this parameter is specified, a trap occurs 
upon completion of the specified WRITES operation. This 
parameter, which is optional, initializes offset location F.BKDN. 
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This address value may also be made available to FCS through 
either the FDBKSA or the FDBKSR macro, and, if so specified, need 
not be present in the WRITES macro call. 


If the address of an AST service routine is not specified through 
any available means, no AST trap occurs at the completion of 
block I/O operations. 


err 


The symbolic address of an optional error-handling routine, which 
you coded. 


When this macro is issued, the virtual block number (that is, the bkvb 
parameter) is checked to ensure that it references a block within the 
file's allocated space; if it does, the block is written. If the 
specified block is not within the file's allocated space, FCS attempts 
to extend the file. If this attempt is successful, the block is 
written; if not, an error code indicating the reason for the failure 
of the extend operation is returned to the I/O status block and _ to 
offset location F.ERR of the associated FDB. 


If FCS determines that the file must be extended, the actual extend 
operation is performed synchronously. After the extend operation has 
been successfully completed, the WRITES operation is queued, and only 


then is control returned to the instruction immediately following the 
WRITES macro. 


The following examples show how the WRITES macro may be used in a 
program: 


WRITES RO 


This example specifies only the FDB address and assumes that all other 
required values are present in the FDB. 


WRITES #OUTFDB, #OUTBUF, #BUFSIZ, #VBNADR, #22. 


This example reflects explicit declarations for the FDB, the _ block 
buffer address, the block buffer size, the virtual block number 
address, and the event flag number for’ signalling block I/O 
completion. 


WRITES RO,,,,#22.,#IOSADR, #ASTADR, ERRLOC 


This example shows null specifications for three parameter fields, 
then continues with the event flag number, the address of the I/0 
status block, and the address of the AST service routine. Finally, it 
specifies the address of an error-handling routine, which you coded. 


NOTE 
You can use RO only to pass the FDB_ address. Any 


other use of RO when you issue the WRITES macro will 
fail. 


3.16.2 The FDB Relevant to WRITES Operations 


WRITES operations require the presence of the same information in the 
FDB as READS operations (see Section 3.15.2). 
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3.17 WAITS - WAIT FOR BLOCK I/O COMPLETION 


The WAITS macro, which is issued only with READS and WRITES 
operations, suspends program execution until the requested block 1/0 
transfer is completed. This macro may be used to synchronize a_ block 
I/O operation that depends on the successful completion of a previous 
block I/O transfer. 


As noted in Section 3.15 in connection with the READS macro, you can 
specify an event flag number through the bkef parameter. This event 
flag number is used during READS (or WRITES) operations to indicate 
the completion of the requested transfer. If desired, you can issue a 
WAITS macro (specifying the same event flag number and I/O status 
block address) following the READS (or WRITES) macro. 


In this case, the READS (or WRITES) operation is initiated in the 
usual manner, but the Executive suspends program execution until the 
specified event flag is set, indicating that the I/O transfer has been 
completed. The system then returns’ information to the I/O status 
block, indicating the success or failure of the operation. FCS then 
moves the I/O status block success or failure indicator into offset 
location F.ERR of the associated FDB, and returns with the carry 
condition code in the Processor Status Word cleared if the operation 
is successful, or set if the operation is not successful. Task 
execution then continues with the instruction immediately following 
the WAITS macro. 


The system returns the final status of the I/O operation to the I/0 
Status block (see Section 2.8.2) upon completion of the requested 
operation. A positive value (+) indicates successful completion, and 
a negative value (-) indicates unsuccessful completion. 


Event flags are discussed in further detail in Section 2.8.1. 


3.17.1 Format of WAITS Macro 
Format 

WAITS fdb,bkef,bkst,err 
Parameter 
fdb 


A symbolic value of the address of the associated FDB. 
bkef 


A numeric value specifying the event flag number to be used for 
synchronizing block I/O operations. The WAITS macro causes task 
execution to be suspended by invoking the .WAITFOR system 
directive. This parameter must agree with the corresponding 
(bkef) parameter in the associated READS or WRITES macro. 


If this parameter is not specified, either in the WAITS macro 
call or the associated READS or WRITE macro, FDB offset location 
F.BKEF is assumed to contain the desired event flag number, as 
previously initialized through the bkef parameter of the FDBKSA 
or the FDBKSR macro. 
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bkst 


The symbolic address of the I/O status block in your program (see 
Section 2.8.2). Although this parameter is optional, if it is 
specified, it must agree with the corresponding (bkst) parameter 
in the associated READS or WRITES macro. 


If this parameter is not specified, either in the WAITS macro 
call or the associated READS or WRITES macro, FDB offset location 
F.BKST is assumed to contain the address of the I/O status block, 
as previously initialized through the bkst parameter of the 
FDBKSA or the FDBKSR macro. If F.BKST has not been initialized, 
no information is returned to the I/O status block. 


err 


The symbolic address of an optional error-handling routine, which 
you coded. 


The following examples show how the WAITS macro may be used in a 
program. 


WAITS RO 

WAITS #INFDB, #25. 

WAITS RO,#25.,#IOSTAT 
WAITS RO, , #IOSTAT, ERRLOC 


The first example assumes that RO contains the address of the 
associated FDB; furthermore, because no flag number (bkef parameter) 
is specified, offset location F.BKEF is assumed to contain the desired 
event flag number. If this cell in the FDB contains 0, event flag 
number 32(decimal) is used by default. 


The second example shows an explicit specification of the FDB address 
and specifies 25(decimal) as the event flag number. Again, in this 
example, the FDB is assumed to contain the address of the I/0 status 
block. In contrast, the third example shows an explicit specification 
for the address of the I/O status block. 


The fourth example contains a null specification for the event flag 
number, and, in addition, specifies the address of an error-handling 
routine, which you coded. 


Please note that the WAITS macro associated with a given READS or 
WRITES operation need not be issued immediately following the macro to 
which it applies. For example, the following sequence is typical: 


1. Issue the desired READS or WRITES macro. 


2. Perform other processing that is not dependent on the 
completion of the requested block I/O transfer. 


3. Issue the WAITS macro. 


4. Perform the processing that is dependent on the completion of 
the requested block I/O transfer. 
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When performing several asynchronous transfers in the same general 
sequence as described previously, a separate buffer, I/O status block, 
and event flag must be maintained for each operation. If you intend 
to wait for the completion of a given transfer, the appropriate event 
flag number and I/O status block address must be specified in the 
associated WAITS macro. 


NOTE 


You can use RO only to pass the FDB_ address. Any 
other use of RO when you issue the WAITS macro will 
fail. 


3.18 DELET$ - DELETE SPECIFIED FILE 


The DELETS$ macro causes the directory information for the file 
associated with the specified FDB to be deleted from the appropriate 
UFD. The space occupied by the file is then deallocated and returned 
for reallocation to the pool of available storage on the volume. 


This macro can be issued for a file that is either open or closed. If 
issued for an open file, that file is then closed and deleted; if 
issued for a closed file, that file is deleted only if the filename 
string specified in the associated dataset descriptor or default 
filename block contains an explicit file version number (including 0 
and -l). 


NOTE 
If the DELETS macro is issued for use with a file 
containing sensitive information, it is recommended 
that you zero the file before closing it, or reformat 
the disk to destroy the sensitive information. 
(Although DELETS$ logically removes a file, the 
information physically remains on the volume until 


written over with another file, and could be analyzed 
by unauthorized user tasks.) 


3.18.1 Format of DELETS Macro 
Format 
DELETS fdb,err 
Parameter 
fdb 
A symbolic value of the address of the associated FDB. 
err 


The symbolic address of an optional error-handling routine, which 
you coded. 


FILE-PROCESSING MACROS 
The following examples show how the DELETS macro may be used in 
program. 
DELETS RO 
DELETS #OUTFDB, ERRLOC 


DELET$ R0O,ERRLOC 


CHAPTER 4 


FILE CONTROL ROUTINES 


This chapter describes a set of file control routines that you can 
invoke in MACRO-11 programs to perform the following functions: 


@e Read or write default directory string descriptors in program 
section SSFSR2. 


@e Read or write the default UIC word in program section SSFSR2. 


e Read or write the default file protection word in program 
section SSFSR2. 


e Read or write the file owner word in program section S$SFSR2. 


e Convert a directory string from ASCII to binary, or binary to 
ASCII. 


e Fill in all or part of a filename block from a dataset 
descriptor or default filename block. 


e Find, insert, or delete a directory entry. 


e Set a pointer to a byte within a virtual block or to a_ record 
within a file. 


@e Mark a place ina file for a subsequent OPENSx operation. 
e Issue an I/O command and wait for its completion. 

@e Rename a file. 

e Extend a file. 

e Truncate a file. 

e Mark a temporary file for deletion. 

e Delete a file by filename block. 


@ Perform device-specific control functions. 


4.1 CALLING FILE CONTROL ROUTINES 
The CALL macro invokes file control routines (JSR PC, dst). The Task 
Builder includes these routines from the system object library 
({1,1]SYSLIB.OLB) at task-build time and incorporates them into your 
task. Your task calls the following file control routines: 

CALL «-RDFDR 


CALL -EXTND 


Before your task issues the CALL macro, certain file control 
require that specific registers be preset with requisite information. 


The descriptions 


requirements. 


Upon 
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respective 
to 


your 


preserved except for those that have 


changed. 


If a file control routine detects an error, 
location 


indication 


present. 


to FDB 
control routines do not 
The following file control routines are listed according to 


error 


whether they return error indications. 


Normal Error Return 
(Carry bit and F.ERR) 


No Error Return 


task registers are 


explicitly specified 


Carry bit 
certain file 
indications 


-ASCPP - RDFDR 
- PARSE -WDFDR 
- PRSDV -RDFUI 
-PRSDI -WDFUI 
- PRSDV -RDFFP 
-ASLUN «WDFFP 
- FIND - RFOWN 
- ENTER -WFOWN 
- REMOV - PPASC 
-GTDIR -MARK 

-GTDID 

«POINT 

- POSRC 

-POSIT 

-XQIO 

- RENAM 

- EXTND 

- TRNCL 

-MRKDL 

- DLFNB 

-CTRL 


Appendix I lists the error codes’ that the routines listed in the 
opening of Chapter 4 return in FDB offset location F.ERR. 


4.2 DEFAULT DIRECTORY STRING ROUTINES 


The .RDFDR and .WDFDR routines read and write directory string 
descriptors. 


a 


4.2.1 .RDFDR - Read $$FSR2 Default Directory String Descriptor 


Your task calls the .RDFDR routine to read default directory string 
descriptor words previously written by the .WDFDR routine into program 
section S$SFSR2 of the FSR. These descriptor words define the address 
and the length of an ASCII string that contains the default directory 
string. This directory string is the default directory that FCS uses 
when one is not specified in a dataset descriptor. 


If you have not established default directory string descriptor words 
in program section $SFSR2 by using the .WDFDR routine described in the 
following text, the descriptor words in program section $$FSR2 are 
null. FCS uses a default directory (when one is not specified ina 
dataset descriptor) corresponding to the User Identification Code 
(UIC) under which the task is running. 
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When called, the .RDFDR routine returns values in the following 
registers: 


Rl contains the size (in bytes) of the default directory string 
"in program section $SFSR2. 


R2 contains the address of the default directory string in 
program section S$SFSR2. If no default directory string 
descriptor words have been written by .WDFDR, R2 equals 0. 


4.2.2 .WDFDR - Write New S$$FSR2 Default Directory String Descriptor 


Your task calls the .WDFDR routine to create default directory string 
descriptor words in program section S$SFSR2. For example, if your 
program is to operate on files in the directory [220,220], regardless 
of the UIC under which the program runs, you can establish default 
directory string descriptor cells in program section S$$FSR2 to point 
to this alternate directory string [220,220] created elsewhere in the 
program. To do this, first create the desired directory string 
through an .ASCII directive. Then, by calling the .WDFDR routine, you 
can initialize the default directory string descriptor cells in 
program section S$SFSR2 to point to the new directory string. 


Assume that the task is currently running under default UIC [200,200]. 
You define a new directory string by issuing the following MACRO-11 
directive: 

NEWDDS: eASCII /[220,220]/ 


By calling the .WDFDR routine, you initialize string descriptor cells 
in program section SSFSR2 to point to the new directory string. 


The following registers must be preset before calling the .WDFDR 
routine: 


Rl must contain the size (in bytes) of the new directory string. 


R2 must contain the address of the new directory string. 


NOTE 


Establishing default directory string descriptor words 
in program section SS$FSR2 does not change the default 
UIC in program section SSFSR2 or the task's 
privileges. 


4.3 DEFAULT UIC ROUTINES 


The .RDFUI and .WDFUI routines read and write the default UIC 
maintained in program section S$S$FSR2 of the file storage region (FSR). 
Unlike the default directory string descriptor that describes an ASCII 
string, the default UIC is maintained as a binary value with the 
following format: 


Bit 15 8 7 0 
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The default UIC in program section SSFSR2 provides directory 
identification information for a file being accessed. FCS uses the 
default UIC only when all other sources of such information have 
failed to specify a directory (refer to Section 4.7.1.2). FCS never 
uses it to establish file ownership or file access privileges. 


Unless you change the default UIC through the .WDFUI routine described 
in the following text, the default UIC in program section SSFSR2 
always corresponds to the UIC under which the task is running. 


4.3.1 .RDFUI - Read Default UIC 


Your task calls the .RDFUI routine to return the default UIC as 
follows: 


R1 contains the binary encoded default UIC as maintained in 
program section SSFSR2. 


4.3.2 .WDFUI - Write Default UIC 


Your task calls the .WDFUI routine to create a new default UIC in 
program section $SFSR2. 


The following register must be preset before calling the .WDFUI 
routine: 


Rl must contain the binary representation of a UIC. 


NOTE 


The .WDFUI routine overrides any default UIC 
descriptor in program section SSFSR2 that was 
previously created by the .WDFDR routine. 


4.4 DEFAULT FILE PROTECTION WORD ROUTINES 


The .RDFFP and .WDFFP routines described in the following text read 
and write the default file protection word in a location in program 
section SSFSR2 of the file storage region (FSR). FCS uses this word 
only when a file is created (for example, by the OPENSW macro call) to 
establish the default file protection values for the new file. Unless 
altered, this value constitutes the default file protection word for 
that file. If the value is -l, it indicates that the volume default 
file protection value is to be used for the new file. 


The default file protection word has four file protection categories: 
world, group, owner, and system. It has the following format: 


Bit 15 12 11 8 7 4 3 0 


WORLD GROUP omen | SYSTEM 
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Each of these four file protection categories has four bits; each bit 
represents the kind of access allowed to a file, as shown in the 
following example: 


Bit 3 2 1 0 


A bit value of 0 indicates that the corresponding file access is to be 
allowed; a bit value of 1 indicates that the access is to be denied. 


4.4.1  .RDFFP - Read SSFSR2 Default File Protection Word 


You call the .RDFFP routine to read the default file protection word 
in program section S$SFSR2 of the FSR. No registers need be set before 
calling this routine. 


When called, the .RDFFP routine returns the following information: 


Rl contains the default file protection word from program 
section SSFSR2. 


4.4.2 .WDFFP - Write New SSFSR2 Default File Protection Word 


You use the .WDFFP routine to write a new default file protection word 
into program section $SFSR2. 


The following register must be preset before calling the .WDFFP 
routine: 


Rl must contain the new default file protection word to be 
written into program section $SFSR2. If this register is set 
to -l, the default file protection values established through 
the appropriate operating system command will be used in 
creating all subsequent new files. 


4.5 FILE OWNER WORD ROUTINES 


The file owner word, like the default file protection word, is a 
location in program section S$SFSR2 of the FSR. Its contents are 
specified by the current program through the .WFOWN routine. If not 
so specified, the file owner word contains 0. 


For nonprivileged users, the owner of a new file corresponds to the 
default UIC specification, as follows: 


e If the volume on which the new file is created is private 
(allocated), the owner UIC is the same as the UIC of the task 
creating the file. 


e If the volume on which the new file is created is a_ system 
volume, the owner UIC is the same as the task's login UIC. 


For privileged users, the owner UIC is always the same as the UIC of 
the task creating the file. 


Note that for files created by privileged or nonprivileged tasks’ that 
are started by a time-scheduled request, the owner UIC is set to the 
UIC specified at task-build time. 
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A specific UIC value can be stored in the file owner word by the 
-WFOWN routine (see Section 4.5.2). All new files then created and 
closed by your task will contain the specified UIC value. 


The format of the file owner word is shown next: 


Bit 15 8 7 0 


The routines for reading and writing the file owner word are described 
in Section 4.5.1. 


NOTE 


The UIC and the file protection word for the file (see 
Section 4.4) must not be set such that the UIC under 
which the task is running does not have access to the 
file. This condition results in a privilege 
violation. 


When a file is created, the owner UIC is always set to either the UIC 
of the task creating the file or the task's login UIC, as previously 
described. However, when closing the file, you can change the owner 
UIC by using the .WFOWN routine. If the file is not closed properly, 
the owner UIC will not change. 


4.5.1  .RFOWN - Read SSFSR2 File Owner Word 
You use the .RFOWN routine to read the contents of the file owner word 
in program section $SFSR2. No registers need be preset before calling 
this routine. 
When called, the .RFOWN routine returns the following information: 

Rl contains the file owner word (UIC). If the current program 


has not previously established the contents of the file 
owner word through the .WFOWN routine, Rl contains 0. 


4.5.2 .WFOWN - Write New SSFSR2 File Owner Word 


You use the .WFOWN routine to initialize the file owner word in 
program section SSFSR2. 


The following register must be preset before calling this routine: 


Rl must contain a file owner word to be written into SSFSR2. 


4.6 ASCII/BINARY UIC CONVERSION ROUTINES 


Your task calls the .ASCPP and .PPASC routines to convert a directory 
string from ASCII to binary, or binary to ASCII. 
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4.6.1 .ASCPP - Convert ASCII Directory String to Equivalent Binary 
UIC 


Your task calls the .ASCPP routine to convert an ASCII directory 
string to its corresponding binary UIC. 


The following registers must be preset before calling this routine: 


R2 must contain the address of the directory string descriptor 
in your program (see Section 2.4.1) for the string to be 
converted. 


R3 must contain the address of a word location in your program 
to which the binary UIC is’ to be returned. The member 
number is stored in the low-order byte of the word, and the 
group number is stored in the high-order byte. 


4.6.2 .PPASC - Convert UIC to ASCII Directory String 


Your task calls the .PPASC routine to convert a binary UIC to its 
corresponding ASCII directory string. 


The following registers must be preset before calling this routine: 


R2 must contain the address of a storage area within your 
program into which to place the ASCII string. The resultant 
string can be up to nine bytes in length, for example, 
{200,200]. 


R3 must contain the binary UIC value to be converted. The 
low-order byte of the register contains the member number, 
and the high-order byte of the register contains the group 
number. 


R4 must contain a control code. Bits 0 and 1 of this’ register 
indicate the following: 


Bit 0 is set to 0 to suppress leading zeros (for example, 001 
is returned as 1). Bit 0 is set to 1 to indicate that 
leading zeros are not to be suppressed. 


Bit 1 is set to 0 to place separators (Square brackets’ and 
commas) in the directory string (for example, [{10,20]). 
Bit 1 is set to 1 to suppress separators (for example, 
1020). 


The .PPASC routine adds to the contents of R2, allowing R2 to point to 
the byte immediately following the last byte in the converted 
directory string. 


4.7 FILENAME BLOCK ROUTINES 


FCS provides the .PARSE, .PRSDV, .PRSDI, .PRSFN, and .ASLUN' routines, 
which perform functions related to a specified filename block. These 
routines are described in the following sections. FCS provides’ the 
Main support for logical name translation in these routines. 
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4.7.1 Logical Name Translation 


When FCS obtains a device name or a file specification, it examines 
the leftmost component to check for the presence of a logical name. 
It does this by checking whether the leftmost character string, which 
may consist only of alphanumeric characters, dollar signs (S$), or 
underscores ( ), ends in either a colon (:) or a space ( ). If it 
does, FCS recognizes the character string as a logical name and makes 
an attempt to translate the entire character string. If FCS finds an 
equivalence name, the original information that the logical name 
represents, the equivalence name is merged with the file specification 
without the logical name. If the leftmost character string ends in 
any character other than a space or colon, FCS uses the string as a 
file specification. 


In the following example, the first line shows how to specify a file 
specification. The second line shows the use of a logical name to 
specify the location of a file. 


S$ TYPE ALPHA 
S$ TYPE DISK:ALPHA 


In the first line, FCS obtains the file specification ALPHA and checks 
to see if ALPHA is a logical name because ALPHA is the leftmost (and 
in this example, the only) component of the file specification. In 
the second line, FCS checks to see if DISK, the leftmost component, is 
a logical name. FCS does not check ALPHA. 


The system stores logical names in four logical name tables. When FCS 
translates logical names, it searches first the task table, then the 
session table, then the group table, and finally the system table, and 
uses the first match it finds. 


4.7.1.1 Iterative Translation - When FCS translates logical names in 
file specifications, the logical name translation can be iterative. 
That is, after FCS translates a logical name in the file 
specification, it continues to translate and repeats the process of 
translating the file specification if it finds the presence of a 
logical name. 


NOTE 


Use the ASSIGN command for all file-specification 
arguments. ASSIGN performs several checks to insure 
that the logical names are syntactically correct. 


As an example of iterative translation, consider logical name _ table 
entries made with ASSIGN commands as follows: 


S$ ASSIGN DBl: DISK 
S ASSIGN REPORT DISK: [HUMIDO]WEATHER.SUM 


The first ASSIGN command equates the logical name DISK to the device 
DB1:. The second ASSIGN command equates the logical name REPORT to 
the file specification DISK: [HUMIDO]WEATHER.SUM. In subsequent 
commands, or in programs you execute, you can refer to the logical 
name REPORT. For example, 


S$ TYPE REPORT 
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When FCS attempts to translate the logical name REPORT, it checks’ the 
logical name tables and finds the equivalence name 
DISK: [HUMIDO]WEATHER.SUM. It then checks the file specification for 
the presence of a logical name; if it finds a match in one of the 
logical name tables (DISK in this example), it translates that logical 
name also. When the logical name translation is complete, the 
following translated file specification results: 


DB1: [HUMIDO]WEATHER.SUM 


FCS limits logical name translation to ten levels. If you define a 
logical name to more than ten levels or create a circular definition, 
an error occurs when you use the logical name. 


If a device name or file specification is preceded by an underscore 
(_), the logical translation process stops. In the example, 


TYPE REPORT 


FCS would look for the file REPORT. in your default device and 
directory. Note also that if an extension or version are included 
with the file name, it is not considered for logical translation. In 
the example, 


TYPE REPORT.TXT 


FCS would look for the file REPORT.TXT in your default device and 
directory. 


4.7.1.2 Logical Translation Process - The following three basic 
operations occur during the logical translation process: 


1. Parsing the file specification - FCS determines the location 
and length of the various parts of the primary file 
specification. It sets flags indicating which parts were 
present and which parts contain wild cards. The length and 
location of the string following the file specification is 
also determined. 


2. Expanding the string - FCS takes the first portion of the 
string and attempts to translate it. The first portion could 
be a logical name. A logical name can be a device name or a 
file name. If there is a logical name string to equivalent 
string translation, FCS uses the equivalent string as_ the 
secondary string in a merge. The primary string for this 
merge is the original file specification less the logical 
name. This operation is reiterative until one of the 
following occurs: 


- There is no logical name to translate. 
- The translation fails. 
- The result of the translation is not a file specification. 


- The recursion limit of more than ten levels of translation 
has occurred. 


- The first character is an underscore (_). 


3. Merging the specifications - FCS generates a merged string 
from the primary and the default string. The merged string 
consists of the primary string with any missing components 
filled in from the default string. 
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4.7.2 .PARSE - Fill in All File Name Information 


FCS includes the main support for logical name translation in the FCS 
-PARSE directive. When the .PARSE routine receives a string, the 
-PARSE routine performs any necessary logical expansion and parses the 
resultant string. 


If you use logical name parsing, logical translation is performed 
first. If you have not requested logical name translation (as when it 
has already been done by CSI$4), the FL.AEX bit should be set in the 
F.FLG byte in the’ FDB. Setting this bit disables logical name 
translation. 


When called, the .PARSE routine first zeros the filename block pointed 
to by Rl and then stores the following information in the filename 
block: 

e The ASCII device name (N.DVNM) 

e The binary unit number (N.UNIT) 

e The directory ID (N.DID) 

e The Radix-50 file name (N.FNAM) 

@ The Radix-50 file type or extension (N.FTYP) 


e The binary file version number (N.FVER) 


For ANSI magnetic tape file names, the following information is stored 
in the filename block: 


e The ASCII device name (N.DVNM) 

e The binary unit number (N.UNIT) 

e The file name as 17 ASCII bytes (N.ANM1 and N.ANM2) 
e The binary file version number (N.FVER) 


In addition, the .PARSE routine calls the .ASLUN routine to assign the 
LUN associated with the FDB to the device and unit currently specified 
in the filename block. 


Both formats for filename blocks are shown in detail in Appendix B. 


Before the .PARSE routine can be called, the FINITS macro (see Section 
2.6) must be invoked explicitly in your program, or it must be invoked 
implicitly through a prior OPENSx macro call. Note, however, that 
your task can issue the FINITS call only once in the initialization 
section of the program; that is, the FINITS operation must _ be 
performed only once per task execution. Furthermore, FORTRAN programs 
issue a FINITS call at the beginning of task execution; therefore, 
MACRO-11 routines used with the FORTRAN object time system must not 
issue a FINITS macro. 


The following registers must be preset before calling the .PARSE 
routine: 


RO must contain the address of the desired FDB. 


Rl must contain the address of the filename block to be filled 
in. This filename block is usually, but not necessarily, the 
filename block within the FDB specified in RO (that is, RO + 
F.FNB). 
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R2 must contain the address of the desired dataset descriptor if 
-PARSE is to access a dataset descriptor in filling in the 
specified filename block. This structure is usually, but not 
necessarily, the same as that associated with the FDB 
specified in RO (that is, the dataset descriptor pointed to 
by the address value in F.DSPT). 


If R2 contains 0, a dataset descriptor has not been defined; 
therefore, the dataset descriptor logic of the .PARSE routine 
is bypassed. 


R3 must contain the address of the desired default filename 
block for the .PARSE routine to access a default filename 
block in filling in the specified filename block. This 
default filename block is usually, but not necessarily, the 
same as the one associated with the FDB specified in RO (that 
is, the default filename block pointed to by the address 
value in F.DFNB). 


If R3 contains 0, a default filename block has not been 
defined; therefore, the default filename block logic of the 
-PARSE routine is bypassed. 


Thus, RO and Rl each must contain the address of the appropriate data 
Structure, while either R2 or R3 must contain the address of the 
desired filename information. Both R2 and R3, however, may contain 
address values if the referenced structures both contain information 
required in filling in the specified filename block. 


The .PARSE routine fills in the specified filename block in the order 
described in the following sections. 


4.7.2.1 Device and Unit Information - The .PARSE routine first tries 
to fill in the filename block with device (N.DVNM) and unit (N.UNIT) 
information. The following operations are performed until the 
required information is obtained from the specified data structures: 


l. If the address of a dataset descriptor is specified in R2 and 
the dataset descriptor contains a device string, the .PARSE 
routine moves the device and unit information from the 
dataset descriptor into the specified filename block. 


2. If step 1 fails, and if the address of a default filename 
block is specified in R3, and the default filename block 
contains a nonzero value in the device name field, the .PARSE 
routine moves the device and unit information from the device 
name field into the specified filename block. 


3. If step 2 fails, the .PARSE routine uses the device and unit 
currently assigned to the logical unit number in offset 
location F.LUN of the specified FDB to fill in the filename 
block. 


This feature allows a program to use preassigned logical 
units that are assigned through either the device assignment 
(ASG) option of the Task Builder or one of the _ following 
commands: ASSIGN in DCL or ASN in MCR. In this case, you 
simply avoid specifying the device string in the dataset 
descriptor and the device name in the default filename block. 


4. If the logical unit number in F.LUN is currently unassigned, 
the .PARSE routine assigns this number to the system device 
(SY0O:). 
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The .PARSE routine first determines the device and unit, assigns’ the 
logical unit number, and then invokes the GLUNS directive to obtain 
necessary device information. The required information obtained by 
GLUNS is placed by the .PARSE routine into the following offsets in 
the filename block pointed to by R1L: 


N.DVNM - Device Name Field, which contains the redirected device 
name. 

N.UNIT - Unit Number Field, which contains the redirected unit 
number. 


Additionally, the .PARSE routine places the information returned by 
GLUNS into the following offsets in the FDB, which RO points to: 


F.RCTL - Device Characteristics Byte. This cell contains 
device-dependent information from the first byte of the 
third word returned by the GLUNS directive. The bit 
definitions pertaining to the device characteristics 
byte are described in detail in Table A-l. If desired, 
you can examine this cell in the FDB to determine the 
characteristics of the device associated with the 
assigned LUN. 


F.VBSZ - Device Buffer Size Word. This location contains’ the 
information from the sixth word returned by the GLUNS 
directive. The value in this cell defines the device 
buffer size (in bytes) of the device associated with 
the assigned LUN. 


The GLUNS directive is described in detail in the RSX-11M/M-PLUS' and 
Micro/RSX Executive Reference Manual... 


4.7.2.2 Directory Identification Information - The N.DID field in the 
filename block contains the following information: 


Word Meaning 
l File ID 
2 File Sequence Number 
3 Reserved 


The .PARSE routine moves these three words from the Master File 
Directory (MFD) to the N.DID field in the filename block. The file ID 
is the header number of the header (in the index file) for a User File 
Directory. The .FIND routine uses the file ID to locate and search a 
UFD and fill in the N.FID field in the filename block. The N.FID has 
the same format as the N.DID field except that it identifies the 
header number of the header for a user data file. The file sequence 
ss is incremented each time a file header is reused for a new 
ile. 


Following the operations described in the preceding section, .PARSE 
attempts to fill in the filename block with directory identification 
(N.DID) information. The methods for obtaining this information are 
as follows: 


l. If your task specifies the address of a dataset descriptor in 
R2 and the dataset descriptor contains a directory string, 
FCS uses that directory string to find the associated UFD in 
the MED. The resulting file ID is then moved into the 
directory-ID field of the specified filename block. 
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If step 1 fails, and your task specifies the address of a 
default filename block in R3, and the default filename block 
contains a nonzero directory ID, the contents of the default 
filename block are moved into the specified filename block. 


Because none of the parameters of the NMBLK$ macro call (see 
Section 2.4.2) initialize the three words starting at offset 
location N.DID in the default filename block, your task must 
initialize these cells manually. Or your task can call the 
.-GTDIR routine (see Section 4.9.1) or the .GTDID routine (see 
Section 4.9.2). Note that these routines can also initialize 
a specified filename block directly with required directory 
information. 


If neither step 1 nor step 2 yields the required directory 
string, the .PARSE routine examines the default directory 
string words in program section SSFSR2. If your program has 
previously initialized these words through use of the .WDFDR 
routine, FCS uses the string described as the default 
directory. 


If steps 1 through 3 fail to produce directory information, 
FCS uses the binary value stored in the default UIC word in 
program section S$SFSR2 as the directory identifier. Unless 
changed by you through the .WDFUI routine, this word contains 
the UIC under which the task is running. 


NOTE 


The .PARSE routine does not accept UICS that contain 
wildcards. Additionally, the .PARSE routine does not 
set filename block status word (N.STAT) bits NB.SD1 or 
NB.SD2 (group and owner wildcard specifications, 
respectively). 


File Name, File Type, and File Version Information - After 


completing the operations described in the preceding section, the 
-PARSE routine attempts to obtain file name information (N.FNAM, 


N.FTYP, 


ls 


and N.FVER), as follows: 


If your task specifies the address of a dataset descriptor in 
R2 and this structure contains a filename string, the file 
name information therein is moved into the specified filename 
block. 


If your task specifies the address of a default filename 
block in R3, and one or more of the file name, file type, and 
file version number fields of the dataset descriptor that you 
specified in R2 are null, the corresponding fields of the 
default filename block fill in the specified. filename block. 


If neither step 1 nor step 2 yields the requisite file name 
information, any specific fields not available from either 
source remain null. 


NOTE 


If a period (.) appears in the filename string without 
an accompanying file type designation (for example, 
TEST. or TEST.;3), FCS interprets the file type as 
being explicitly null. In this case, the default file 
type is not used. 


FILE CONTROL ROUTINES 


Similarly, if a semicolon (;) appears in the filename 
string without an accompanying file version number 
(for example, TEST.DAT;), FCS also interprets the file 
version number as being null; again, the default file 
version number is not used. This information 
concerning semicolons in filename strings does not 
apply to the 17-byte ASCII filename strings supported 
for ANSI magnetic tape. 


4.7.2.4 Using the FDB Extension for Logical Names - FCS uses the FDB 
extension to obtain the correct directory string. The extension has 
the following format: 


-BYTE Extension length 

- BYTE Unused 

~BYTE Length of the directory string buffer 

~ BYTE Length of the directory string (filled in by .PRSDI) 
- WORD Address of the directory string buffer 


The FDB extension block and the directory string buffer are allocated 
in your task's address space. You fill in the address, the length of 
the buffer, and the length of the ‘extension into the appropriate 
locations in the FDB extension block. You then place the address of 
the extension block in the offset F.EXT in the FDB. When the 
directory parsing code detects that F.EXT has a value, it uses the 
value as an address and moves the directory string into the buffer. 
It also puts the length of the actual directory string into the 
appropriate byte of the extension. This directory string is always 
filled in unless FCS obtains the directory from the default name 
block, because the default name block does not contain the directory 
string. If FCS obtains the directory from the default name block, FCS 
sets the directory length to zero. 


4.7.2.5 Other Filename Block Information - After performing all the 
previously described operations, the .PARSE routine also fills in the 
status word (offset location N.STAT) of the filename block specified 
in Rl. 


The bit definitions for this word are presented in Table B-2. Note 
that in this table the directory, device, file name, file type, or 
file version number specification pertains to ASCII data supplied 
through the dataset descriptor pointed to by R2. 


In addition, the .PARSE routine zeros offset location N.NEXT in the 
filename block pointed to by Rl. This action has implications for 
wildcard operations, as described in Section 4.8.1. 


4.7.2.6 .EXPLG Module (Expand Logical) - The .~.EXPLG module expands a 
logical name and returns ae pointer to the task that points to the 
expanded string. The module has the following inputs and outputs: 


INPUTS: R2 - Pointer to the dataset descriptor of the string to 
be expanded. 


OUTPUTS: R2 - Pointer to the dataset descriptor of the expanded 
string. All other registers are preserved. 
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This routine expands the string into the same buffer that the .PARSE 
routine and CSIS$4 use for input files; therefore, caution is advised 
if you use this method. In addition, the call only accepts logical 
names that expand into a correct FCS file specification. The 
inclusion of a node specifier or other non-FCS characters results in 
an error being returned. 


4.7.3 .PRSDV - Fill in Device and Unit Information Only 


The .PRSDV routine is identical to the .PARSE routine, except that it 
performs only those operations associated with requisite device and 
unit information (see Section 4.7.1.1). The .~PRSDV routine zeros’ the 
filename block pointed to by Rl, calls the .PARSE routine to operate 
on the device and unit fields in the specified dataset descriptor or 
default filename block, and assigns the logical unit number contained 
in offset location F.LUN of the specified FDB. 


After the logical device translation is performed, .PRSDV fills’ the 
filename block with the required device and unit information. If the 
device is LB:, the actual physical device name and unit are placed in 
the filename block. If the logical device expands to contain anything 
other than a device specification, for example, a directory or a 
filename, the remainder is ignored. Setting the FL.AEX bit (see 
Chapter 6) disables logical expansion for the device and unit 
information. 


4.7.4 .PRSDI - Fill in Directory Identification Information Only 


The .PRSDI routine is identical to the .PARSE routine, except that it 
performs only those operations associated with requisite directory 
identification information (see Section 4.7.1.2). The .~PRSDI routine 
performs a - PARSE operation on the directory identification 
information (N.DID) field in the specified dataset descriptor or 
default filename block. The .PRSDI routine does not perform any 
logical name expansion. 


4.7.5 .PRSFN - Fill in File Name, File Type, and File Version Only 


The .PRSFN routine is identical to the .PARSE routine, except that it 
performs only those operations associated with requisite file name, 
file type, and file version information (see Section 4.7.1.3). This 
routine performs a .PARSE operation on the file name, file type, and 
file version information fields (N.FNAM, N.FTYP, N.FVER) in the 
specified dataset descriptor or default filename block. The .PRSFN 
routine does not perform any logical name expansion. 


4.7.6 .ASLUN - Assign Logical Unit Number 


The .ASLUN routine assigns a logical unit number to a specified device 
and unit and returns’ the device information to a specified FDB and 
filename block. 
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The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 


Rl must contain the address of the filename block where the 
desired device and unit information are located. This 
filename block is usually, but not necessarily, within the 
FDB specified by the address in RO. 


If the device name field (offset location N.DVNM) of the filename 
block pointed to by Rl contains a nonzero value, the specified device 
and unit are assigned to the logical unit number contained in offset 
location F.LUN in the FDB pointed to by RO. 


If offset location N.DVNM in the filename block contains 0, then the 
device and unit currently assigned to the specified logical unit 
number are returned to the appropriate fields of the filename block. 


Finally, if the specified logical unit number is not assigned to a 


specific device, the .ASLUN routine assigns it to the system device 
(SY0:) by default. 


The information returned to the specified filename block and _ the 
specified FDB is identical to that returned by the device and unit 
logic of the .PARSE routine (see Section 4.7.1.1). 


4.8 DIRECTORY ENTRY ROUTINES 


The .FIND, .ENTER, and .REMOV routines find, insert, and delete 
directory entries. The term “directory entry" refers to entries in 
both the Master File Directory (MFD) and the User File Directory 
(UFD). 


4.8.1 .FIND - Locate Directory Entry 


You call the .FIND routine to locate a directory entry by file name 
and fill in the file identification field (N.FID) of a specified 
filename block. 


The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 


Rl must contain the address of a filename block. This filename 
block is usually, but not necessarily, within the FDB 
specified by the address in RO. 


When invoked, the .FIND routine searches the directory file specified 
by the directory-ID field of the filename block. This file is 
searched for an entry that matches the specified file name, file type, 
and file version number. Two special file versions are defined: 


e Version 0 is matched by the latest (largest) version number 
encountered in the directory file. 


e Version -l is matched by the oldest (smallest) version number 
encountered in the directory file. 


If either of these special versions is specified in the filename 
block, the matching version number is returned to the filename block. 
In this way, the actual version number is made available to. the 
program. 
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Certain wildcard operations require the use of the .FIND routine. 
Three bits in the filename block status word (see N.STAT in Table B-2) 
indicate whether a wildcard (*) was specified for a file name, a file 
type, or a file version number field. If the wildcard bit in N.STAT 
is set for a given field, any directory entry matches that 
corresponding field. Thus, if the file name and file version number 
fields contain wildcard specifications (*), and the file type field is 
specified as .OBJ (that is, *.OBJ;*), the first directory entry 
encountered that contains .OBJ in the file type field matches. 


When a wildcard match is found, the complete file name, file type, and 
file version number fields of the matching entry are returned to the 
filename block, along with the file-ID field (N.FID). Thus, the 
program can determine the actual name of the file just found. Offset 
location N.NEXT in the filename block is also set to indicate where 
that directory entry was found in the directory file. FCS uses this 
information in subsequent .FIND operations to locate the next matching 
entry in the directory file. 


For example, the .FIND routine often opens a series of files when 


wildcard specifications are used. The following operations are 
typical: 


1. Call the .PARSE routine. This routine zeros offset location 
N.NEXT in the filename block in preparation for the iterative 
-FIND operations described in step 3. 


2. Check for wildcard bits set by the .PARSE routine in the 
filename block status word (see N.STAT in Table B-2). An 
instruction sequence such as that shown in the following text 
tests for the setting of wildcard bits in N.STAT: 


BIT #NB.SVR!INB.STP!NB.SNM,N.STAT (R1) 
BEQ NOWILD 7;BRANCH IF NOT SET. 
3. If wildcard specifications are present in the filename block 
status word, repeat the following sequence until all the 


desired wildcard files have been processed: 


CALL .FIND 


BCS DONE 7;ERROR CODE IE.NSF INDICATES 
;NORMAL TERMINATION. 
OPENS RO 
Wildcard .FIND operations update offset location N.NEXT in 
the filename block. In essence, the contents of this cell 
provide the necessary information for continuing the 


directory file search for a matching entry. 


4, Perform the desired operations on the file. 


NOTE 


This procedure applies only to the following types of 
wildcard file specifications: 


TEST.DAT;* 
TEST. *;* 

* DAT; * 
TEST.*;5 
*. DAT;3 
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This procedure does not work for the following types 
of wildcard file specifications: 


* .DAT 
TEST.* 


In summary, if a wildcard file specification is present in either the 
file name field or the file type field, the file version number field 
must also contain either an explicit wildcard specification (*) or a 
specific file version number. In the latter case, however, the 
version number cannot be 0, for the latest version of the file, or -l, 
for the oldest version of the file. 


When your task sets NB.ANS, the .FIND operation compares the file name 
against the full 17-character ANSI filename string that is stored in 
the filename block (see Appendix B). When NB.ANS is clear, the file 
name is converted to Radix-50, as described in Appendix G. 


ANSI magnetic tape file names in the following formats can be 
converted to Radix-50: 


e Up to nine Radix-50 characters followed by spaces 


e Up to nine Radix-50 characters followed by a period, followed 
by spaces or by a 3-character file type 


Note that unless NB.ANS is set before the call to .FIND, some file 
names may be incorrectly matched. For example, the names "ABC" and 
"ABC." are considered the same when compared with the name ABC in 
Radix-50. 


When a wildcard operation is performed, the name returned in the 
filename block is normally converted to Radix-50. However, if NB.ANS 
is set, the ANSI filename string is returned as up-to-17 ASCII bytes. 
The first twelve bytes are returned at offset N.ANM1 in the ANSI 
filename block. The remainder are returned at offset N.ANM2. 


It is incorrect to set NB.ANS before a wildcard .FIND operation unless 
both file name and file type are wild, or neither filename nor file 
type are wild. 


To delete a file whose file descriptor entry in the FDB' contains 


wildcards, you must save the values in the fields N.STAT and N.NEXT in 
the FDB, then zero these fields in the FDB. A DELETE call then uses 
the information returned from the last .FIND to delete the file. Once 
the file is deleted, the saved values of N.STAT and N.NEXT must be 
restored in the FDB. 


4.8.2 .ENTER - Insert Directory Entry 


You use the .ENTER routine to insert an entry by file name into a 
directory. 


The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 
Rl must contain the address of a filename block. This filename 


block is usually, but not necessarily, the filename block 
within the FDB specified in RO. 
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If the file version number field of the filename block contains 0, 
indicating a default version number, the .ENTER routine scans the 


entire directory file to determine the current highest version number 
for the file. If a version number for the file is found, this entry 


is incremented to the next higher version number; otherwise, it is set 
to 1. The resulting version number is returned to the filename block, 
making this number known to the program. 


NOTE 


Wildcard specifications cannot be used in connection 
with .ENTER operations. 


4.8.3 .REMOV - Delete Directory Entry 


You use the .REMOV routine to delete an entry from a directory by file 
name. This routine only deletes a specified directory entry; it does 
not delete the associated file. 


The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 


Rl must contain the address of a filename block. This filename 
block is usually, but not necessarily, the filename block 
within the FDB specified in RO. 


Wildcard specifications operate in the same manner as those defined 
for the .FIND routine described in Section 4.8.1. The file version 
number for .REMOV operations must be an explicit number (including 0 
and -l) or ae#wildcard. Each .REMOV operation deletes the next 
directory entry that has the specified file name, file type, and file 
version number. 


4.9 FILENAME BLOCK ROUTINES 


The .GTDIR and .GTDID routines insert directory information in a 
specified filename block. Sections 4.9.1 and 4.9.2, following, 
describe the use and operation of these routines. 


4.9.1 .GTDIR - Insert Directory Information in Filename Block 


You call the .GTDIR routine to insert directory information from a 
directory string descriptor into a specified filename block. 


Before calling this routine, the following registers must be preset: 
RO must contain the address of the desired FDB. 


Rl must contain the address of the filename block in which the 
directory information is to be placed. This filename block 
is usually, but not necessarily, within the FDB specified by 
the address in RO. 


R2 must contain the address of the 2-word directory string 
descriptor in your program. This string descriptor defines 
the size and the address of the desired directory string. 
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This routine performs a .FIND operation for the specified UFD in the 
MFD and returns the resulting directory ID to the three words of the 
specified filename block, starting at offset location N.DID. The 
-GTDIR routine preserves the information in offset locations N.FNAM, 
N.FYTP, N.FVER, N.DVNM, and N.UNIT of the filename block, but clears 
the rest of the filename block. 


You can also use the .GTDIR routine with the NMBLKS macro call (see 
Section 2.4.2) to insert directory information into a specified 
default filename block. 


4.9.2 .GTDID - Insert Default Directory Information in Filename Block 


The .GTDID routine provides an alternative means for inserting 
directory information into a specified filename block. Instead of 
allowing the specification of the directory string, as does the .GTDIR 
routine, this routine uses the binary value found in the default UIC 
word maintained in program section $SFSR2 as the desired UFD. 


Before calling the .GTDID routine, you must preset the following 
registers: 


RO must contain the address of the desired FDB. 


Rl must contain the address of a filename block in which the 
directory information is to be placed. This filename block 
is usually, but not necessarily, within the FDB specified by 
the address in RO. 


When called, the .GTDID routine takes the default UIC from its 1-word 
location in program section S$$FSR2 and performs a .FIND operation for 
the associated UFD in the MFD. The resulting directory ID is returned 
to the three words of the specified filename block, starting at offset 
location N.DID. As does the .GTDIR routine, .GTDID preserves offset 
locations N.FNAM, N.FTYP, N.FVER, N.DVNM, and N.UNIT in the filename 
block, but clears the rest of the filename block. 


The .GTDID routine uses considerably less code than the .GTDIR 
routine. Its input is the binary representation of a UIC rather than 
an ASCII string descriptor. Therefore, it does not invoke the’ .PARSE 
logic; furthermore, .GTDID is specifically for use in programs that 
open files by the OFNBS macro call (see Section 3.6). Such a program 
does not invoke the .PARSE logic because all necessary file name 
information is provided to the program in filename block format. 


Like the .GTDIR routine described in Section 4.9.1, the .GTDID routine 
can be used with the NMBLKS macro call (see Section 2.4.2) to insert 
directory information (N.DID) into a specified default filename block. 
You also have the option to initialize offset location N.DID manually 
with the required directory information. 


The .GTDID routine returns file-ID 177777,177777,0 for nondirectory 
devices such as terminals. 


4.10 FILE POINTER ROUTINES 


The .POINT, .~POSRC, .MARK, and .POSIT routines point to a byte or a 
record within a specified file. Sections 4.10.1 through 4.10.3, 
following, briefly describe the use of these routines and their 
operation. 
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4.10.1 .POINT - Position File to Specified Byte 


You call the .POINT routine to position a file pointer to a specified 
byte in a specified virtual block. If locate mode is in effect for 
record I/O operations, the .POINT routine also updates the value in 
offset location F.NRBD+2 in the associated FDB in preparation for a 
PUTS operation in locate mode. 


The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 
Rl must contain the high-order bits of the virtual block number. 
R2 must contain the low-order bits of the virtual block number. 


R3 must contain the desired byte number within the specified 
virtual block. 


For a description of virtual block numbers and how these 2-word values 
are formed, refer to item 4 in Section 2.2.2.1. 


NOTE : 


Use of the .POINT routine is restricted to files 
accessed with GETS or PUTS macros. For files accessed 
with READS or WRITES macros, use the FDBKSR macro to 
initialize the block access section of the FDB. 


The .POINT routine is used often with the .MARK routine and achieves a 
limited degree of random access with variable-length records. The 
»MARK routine saves the positional information of a file, permitting 
you to temporarily close that file and reopen it later at the same 
position; this procedure is outlined in the following steps: 


1. Call the .MARK routine to save the current positional context 
of the file. 


2. Close the file. 
3. Reopen the file when desired. 


4. Load the information returned by the .MARK routine into Rl, 
R2, and R3. 


5. Call the .POINT routine. The .POINT routine may be called to 
rewind a file on disk or ANSII magnetic tape to its start. 
For this case, Rl and R3 must be set to 0, and R2 must be set 
to 1. The .POINT routine may also be called to rewind a file 
that is open on a terminal. Doing so clears the terminal 
end-of-file condition. 


6. Resume processing of the file. 


4.10.2 .POSRC - Position File to Specified Record 


The .POSRC routine sets up the position information for a file to a 
specified fixed-length record within a file. If locate mode is in 
effect for record I/O operations, the .POSRC routine also updates’ the 
value in offset location F.NRBD+2 in the associated FDB in preparation 
for a PUTS operation in locate mode. . 
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Before calling this routine, you must set offset locations F.RCNM+2 
and F.RCNM in the FDB to the desired record number and ensure that the 
correct record size is reflected in offset location F.RSIZ of the FDB. 


The register RO must be preset before calling the .POSRC routine: 
RO must contain the address of the associated FDB. 


You use the .POSRC routine when performing random access’ PUTS 
operations in locate mode. Normally, PUTS operations in locate mode 
are sequential; however, when you use random access mode, you must 
follow the next procedure to ensure that the record is built at the 
desired location: 


l. Set offset locations F.RCNM+2 and F.RCNM in the associated 
FDB to the desired record number. 


2. Call the .POSRC routine. 


3. Build the new record at the address returned (by the .POSRC 
call) in offset location F.NRBD+2 of the associated FDB. 


4. Perform the PUTS operation. 


4.10.3 .MARK - Save Position Information Context of File 


The .MARK routine allows you to save the current position information 
of a file for later use; you can save the current position information 
of a file, close that file, and later reopen it to the same position. 
The .MARK routine also allows you to alter records within a file; you 
can save the file position, retrieve information elsewhere in that 
file, and return to the saved position of the file to alter the 
desired record. This sequence may be repeated to update any number of 
desired records in the file. The following register must be preset 
before calling the .MARK routine: 


RO must contain the address of the associated FDB before calling 
this routine. 


When called, the .MARK routine returns information to the following 
registers: 


Rl contains the high-order bits of the virtual block number. 
R2 contains the low-order bits of the virtual block number. 


R3 contains the number of the next byte within the virtual 
block. 


R3 points to the next byte in the block. For example, if four GETS 


operations are performed, followed by a call to the .MARK routine, R3 
points to the first byte in the fifth record in the file. 


4.10.4 .POSIT — Return Specified Record Position Information 


The .POSIT routine calculates the virtual block number and the byte 
number locating the beginning of a specified record. 


The following register must be preset before calling this routine: 


RO must contain the address of the associated FDB. 
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In addition, offset locations F.RCNM and F.RCNM+2 in the associated 
FDB must contain the desired record number. 


Unlike the .POSRC routine, which sets up the position information of 
the file to the specified record, .POSIT calculates the positional 
information of a specified record so that a .POINT operation can be 
later performed to position to the desired record. 


The .POSIT routine returns register values identical to those 
described previously for the .MARK routine. 


4.11 QUEUE I/O FUNCTION ROUTINE (.XQIO) 


The Queue I/O Function Routine (.XQIO) executes a specified QIO$§ 
function and waits for its completion. 


The following registers must be preset before calling this routine: 
RO must contain the address of the desired FDB. 


Rl must contain the desired QIOS macro function code. Refer to 
the RSX-11M/M-PLUS I/O Drivers Reference Manual or Micro/RSX 
1/0 Drivers Reference Manual for the desired QIOS macro 
function codes. 


R2 must contain the number of optional parameters, if any, to be 
included in the QIOS directive. 


R3 must contain the beginning address of the list of optional 
QIO$ directive parameters, if R2 contains a nonzero value. 
Refer to the RSX-l11M/M-PLUS I/O Drivers Reference Manual or 
Micro/RSX Drivers Reference Manual for the parameter List. 


4.12 RENAME FILE ROUTINE (.RENAM) 


The .RENAM routine is called to change the name of a file in its 
associated directory. To rename a file, you must specify the address 
of an FDB containing file name information, a LUN, and an event flag 
number. 


If the file to be renamed is open when the call to .RENAM is’ issued, 
that file is closed before the renaming operation is attempted. 


The following registers must be preset before calling this routine: 


RO must contain the address of the FDB associated with the file 
with the original name. 


Rl must contain the address of the FDB containing the desired 
file name information, LUN assignment, and event flag. 


If the renaming operation is successful, a new directory entry is 
created and the original entry is deleted. If the operation is 
unsuccessful, the file is closed under its original name, and_ the 
associated directory is not affected. 


The .RENAM routine uses the absence of ae value in location 
F.FNB + N.FID to indicate that .PARSE must be called to parse a file 
specification (an open file always has a nonzero value in 
F.FNB + N.FID). If neither a dataset descriptor nor a default 
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filename block is present, .PARSE returns a null file name. The 
rename operation then produces a new file name of version ".;1". If a 
Wildcard (*) is part of the input file specification, wildcard 
processing like that described for the .FIND routine occurs. 
Wildcards are not allowed in an output file specification. 


NOTE 


The renaming process is merely a directory operation 
that replaces an old entry with a new entry. The file 
name stored in the file header block is not altered. 


4.13 FILE EXTENSION ROUTINE (.EXTND) 


The .EXTND routine extends either contiguous or noncontiguous’ files. 
The file to be extended can be either open or closed. A call to the 
-EXTND routine disables file truncation. You must explicitly call 
-TRNCL to truncate a file after you call .EXTND. 


The following registers must be preset before calling the .EXTEND 
routine: 


RO must contain the address of the associated FDB. 


Rl must contain a numeric value specifying the number of blocks 
to be added to the file. 


R2 must contain the extension control bits, as appropriate. The 
possible bit configurations for controlling file-extend 
operations are detailed in Table 4-l. This table defines the 
bits in the low-order byte of R2. The high-order 8 bits of 
R2 (Bits 8 through 15) are used with the 16 bits of R1 _ to 
define the number of blocks to be added to the file (see NOTE 
1, which follows). 


NOTE 


1. FCS uses the contents of Rl and the high-order 
byte of R2 (Bits 8 through 15) to perform the 
specified .EXTND operation. Thus, 24 bits of 
magnitude are available for specifying the number 
of blocks by which the file is to be extended. 


2. If a file previously had space allocated to it, a 
contiguous file extension by the .EXTND routine 
cannot be done. You can create a contiguous file 
by opening a new file with a zero allocation and 
calling .EXTND to allocate the desired number of 
blocks. 


3. When writing a new file using QIO$ macros, the 
task must explicitly issue .EXTND calls as 
necessary to reserve enough blocks for the file, 
or the file must be initially created with 
sufficient blocks. In addition, the task must put 
an appropriate value in the FDB for the 
end-of-file block number (F.EFBK) before closing 
the file or rewinding and reading it. 


4. If R2 contains a zero, FCS defaults to 
noncontiguous allocation. 
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In general, when FCS implicitly extends a file, it activates file 
truncation. See Section 4.14 for information on how to turn off file 
truncation. When your program explicitly allocates space to a file, 
either with an OPENS or .EXTND, FCS turns off truncation. To turn off 
file truncation and close the file, call the following routines: 


1. Call the .EXTND routine. Set both Rl and R2 to 0. 


2. Issue the CLOSES macro. 


4.14 FILE TRUNCATION ROUTINE (.TRNCL) 


The .TRNCL routine truncates a file to the logical end of the file, 
deallocates any space beyond this point, and closes the file. 


The following register must be preset before calling this routine: 
RO must contain the address of the associated FDB. 


The file must have been opened with both write and extend access 
privileges. Otherwise, the truncation will fail. 


The close operation will be attempted even if the truncation operation 
fails. If errors occur in both operations, the error code from the 
close operation will be returned. 


FCS turns on truncation when it extends a file. However, when your 
program explicitly calls the .EXTND routine, FCS turns off truncation. 


4.15 FILE DELETION ROUTINES 


FCS provides the .MRKDL and .DLFNB routines for deleting files. 


NOTE 


If you use the .MRKDL or .DLFNB routine to delete a 
file containing sensitive information, you should 
clear the file before closing it or reformat the disk 
to destroy the sensitive information. (Although the 
file is marked for deletion, the information 
physically remains on the volume until written over 
with another file, and could be analyzed by 
unauthorized users.) 


4.15.1  .MRKDL - Mark Temporary File for Deletion 


You use the .MRKDL routine to mark a temporary file for deletion; that 
is, a file created through the OPNTSW macro call (see Section 3.3). 
Such a file has no associated directory entry. 


A call to the .MRKDL routine is issued prior to closing a temporary 
file. The file so marked is then deleted when the file is closed. 
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Table 4-1 
R2 Control Bits for .EXTND Routine 


Value in Low-Order 


Byte of R2 Meaning 
0 Indicates that the file extent is to be 
: noncontiguous. 
200 Indicates that the file extent is to be 
noncontiguous. This clears the contiguous 


file attribute. 


201 Indicates that the contiguous area is to be 
added to the file. This clears’ the 
contiguous file attribute. 


203 Indicates that the largest available 
contiguous area is to be added to the file 
if the desired file extent space is not 
available. This clears the contiguous file 
attribute. 


205 Indicates that this is the initial extent of 
the file. The file is to be contiguous. 


207 Indicates that the largest contiguous area 

. up to the specified extend size is to be 
added to the file. The file is to be 
contiguous. 


210 Indicates that the file is to be extended by 


the default extend size for the volume. The 
extend is to be noncontiguous. 


211 Indicates that the file is to be extended by 
the default extend size for the volume. The 
extend is to be contiguous, whereas the file 
is to be noncontiguous. 


Before calling the .MRKDL routine, you must preset the following 
register: 

RO must contain the address of the associated FDB. This FDB is 
assumed to contain the file identification, device name, and 
unit information of the file to be deleted. 

If the .MRKDL routine is invoked while the temporary file is open, as 
is normally done, the file is deleted unconditionally when it is 


closed. This occurs even if the calling task terminates abnormally 
without closing the file. 


4.15.2 .DLFNB - Delete File by Filename Block 

You use this routine to delete a file by filename block. The .DLFNB 
routine assumes that the filename block is completely filled; when 
called, it closes the file, if necessary, and then deletes the file. 


Before calling this routine, the following register must be preset: 


RO must contain the address of the associated FDB. 


4-26 


FILE CONTROL ROUTINES 


The .DLFNB routine operates in the same manner as the DELETS$ macro 
call (see Section 3.18), but .DLFNB does not require any of the - PARSE 
logic and thus requires less memory than the normal DELETS function. 

Like the DELETS$ operation, however, the .DLFNB operation fails if the 
file to be deleted is not open, and if an explicit file version number 


is missing from offset location N.FVER of the associated filename 
block. 


4.16 DEVICE CONTROL ROUTINE (.CTRL) 
You call the .CTRL routine to perform device-specific control 
functions. The following are examples of .CTRL device-specific 
functions: 

e Rewind a magnetic tape volume set. 


e Position to the logical end of a magnetic tape volume set. 


@e Close the current magnetic tape volume and continue file 
operations on the next volume. 


e Space forward or backward n blocks on a magnetic tape. 


e Rewind a file on a magnetic tape or a terminal 
(record-oriented device). 


e Clear the terminal end-of-file. 
The following registers must be preset before calling this routine to 
perform the first three bulleted items listed previously in this 
section. 

RO must contain the address of the associated FDB. 

Rl must contain one of the following function codes: 


e FF.RWD to rewind a magnetic tape volume set. 


e FF.POE to position to the logical end of a magnetic tape 
volume set. 


@ FF.NV to close the current volume and continue file 
operations on the next volume of a magnetic tape volume 
set. 


R2 must be set to 0. 
R3 must be set to 0. 


When using .CTRL to space forward or backward, you must ensure that 
registers RO, Rl, R2, and R3 contain the following values: 


RO must contain the address of the associated FDB. 
Rl must contain the value FF.SPC. 


R2 must contain the number of blocks to space forward or 


backward. A positive number means space forward; a negative 
number means space backward. 


R3 must contain 0. 
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When using .CTRL to rewind a file, you must ensure that register Rl 
contains the value FF.RWF and that registers R2 and R3 contain 0. 


See Chapter 5 for an explanation of using .CTRL to accomplish magnetic 
tape device-specific functions. 


4.17 BUFFER FLUSH ROUTINE (.FLUSH) 


The buffer flush routine (.FLUSH) writes the block buffer to the file 
being written in record mode. The .FLUSH routine also writes file 
attributes (including F.EFBK and _ F.HIBK, the end-of-file and 
high-allocation block numbers) each time the routine is called. 


Closing the file guarantees that the block buffer is flushed and that 
the file attributes will be written back to the file header. However, 
closing and opening a file frequently, solely to write the block 
buffer, causes high system overhead and unnecessary disk accesses. 


4.17.1 Purpose of the .FLUSH Routine 


When FCS executes a PUTS macro to a disk file, the PUTS macro puts a 
record into the block buffer. When the block buffer is full, or the 
file is closed, FCS writes the block buffer to the file. You cannot 
predict when FCS will actually write the block buffer to the file. 


Some applications may require that a record be written to a file 
immediately. As an example, a task that handles a laboratory device 
may write small amounts of data to a file every few minutes. If the 
System crashes, the contents of the block buffer may not have been 
written to the file. This data may be lost unless a PUTS is 
immediately followed by a call to the .FLUSH routine. As another 
example, the .FLUSH routine should be called by an originating task to 
write data immediately if another task must then read data written by 
that originating task. In these examples, the tasks need not close 
the file to ensure that the data is written to the file. 


4.17.2 When .FLUSH Should Be Used 


Your task should call .FLUSH whenever data should be immediately 
written to a file. 


You need not call the .FLUSH routine for block mode (WRITES) or record 
mode (PUTS) write operations to a record-oriented device; the block 
buffer is always written in these cases. Nothing happens if you call 
-FLUSH when a file is open under these circumstances except the return 
of a cleared Carry bit and status +l (success) in FDB byte F.ERR. 


4.17.3 Performance Considerations Using .FLUSH 


Calling the .FLUSH routine after every PUTS macro can greatly increase 
I/O activity compared to using solely the PUTS macro. One alternative 
is to call the .FLUSH routine after certain intervals have passed or 
after a certain number of calls to PUTS. 
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4.17.4 Using the .FLUSH Routine 
The following register must be preset before calling this routine: 
RO must contain the address of the associated FDB. 
During output, all registers are preserved, the C-bit is clear or set 


to indicate success or failure, and the FDB F.ERR byte contains the 
success or failure code. 


CHAPTER 5 


FILE STRUCTURES 


This chapter describes the structure of files supported by the RSX-11M 
systems. It specifically covers the identical file structure on disk, 
DECtape, and DECtape II and the ANSI file structure on magnetic tape 
supported by the Micro/RSX and RSX-11M/M-PLUS systems. 


The disk, DECtape, and DECtape II file structure is called Files-11; 
the magnetic tape file structure is ANSI standard. 


The Files-11l structure is a file-organization system, which primarily 
determines the way that files and their associated control files are 
arranged on a disk or DECtape. Associated with the Files-1l structure 
is a system of data structures in memory, the most important of which 
include the Volume Control Block, the File Control Block, and _ the 
Device Control Block. Files-1ll structure includes not only the 
physical file and its associated control files, but the necessary 
information in these files that determines the file's size, location, 
content, and various attributes. 


The ANSI standard describes a way of organizing sequential files on a 
Magnetic tape that allows the tape to be used on any computer system. 
The standard includes file structure, labeling, and physical 
characteristics such as end-of-tape length. 


5.1 DISK AND DECTAPE FILE STRUCTURE (FILES-11) 
Disk and DECtape volumes (defined by and associated with a Volume 
Control Block) contain both user files and system files. Disks and 
DECtapes initialized through the DCL command INITIALIZE or MCR command 
INITVOLUME have the standard Files-11l structure built for them. The 
standard system files created by these commands include: 

e Index file 

e Storage allocation file 

e Bad block file 

@ Master File Directory (MFD) 

e Checkpoint file 
Each Files-11 volume has all of these files. A volume may have more 
than one directory file; the system uses these files, created by the 


MCR UFD command or the DCL CREATE/DIRECTORY command for RSX-11M/M-PLUS 
and Micro/RSX systems, to locate user files on the volume. 
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5.1.1 User File Structure 


Data files on disk and DECtape consist of ordered sets of virtual 
blocks; these blocks constitute the virtual structure of the data 
files as they appear to you. Virtual blocks can be read and written 
directly by issuing READS and WRITES macro calls (see Sections 3.15 
and 3.16, respectively). The first block in the file is virtual block 
l; subsequent virtual blocks are numbered in ascending order. 


The virtual blocks of a file are stored on the volume as_ logical 
blocks. Because virtual blocks and logical blocks are equal in size, 
and the logical block size of all:volumes is 256 words, each virtual 
block is also 256 words. When access to a virtual block is requested, 
the virtual block number is mapped into a logical block number. The 
logical block number is’ then mapped to the physical address on the 
associated volume. 


5.1.2 Directory Files 


A directory file contains directory entries. Each entry consists of a 
file name and its associated file number and file sequence number. 
The number of required directory files depends on the number of users 
of the volume. For single-user volumes, only a Master File Directory 
(MFD) is needed; for multiuser volumes, an MFD is required, and one 
User File Directory (UFD) is required for each user of the volume. 


The MFD contains a list of all the UFDs on the volume, and each UFD 
contains a list of all that user's files. UFDs are identified by User 
Identification Codes (UICS). An MCR UFD command or a DCL 
CREATE/DIRECTORY command creates the User File Directory. These 
commands are described in detail in the RSX-11M/M-PLUS MCR Operations 
Manual and the RSX-11M/M-PLUS Command Language Manual, 


Figures 5-1 and 5-2 illustrate the directory structure for single-user 
and multiuser volumes, respectively. 


5.1.3 Index File 


You create the index file for the operating system to use when you 
initialize a volume. During initialization, the information required 
by the system to manage the file is placed in the index file. The 
index file contains volume information and user file header blocks, 
which the system file control primitives (FCP) use to manage the file. 
The file header blocks (see Section 5.1.4) are stored in the index 
file so that they can be located quickly. Furthermore, because a file 
header block is 256 words in length, it can be read into memory with a 
single access. Appendix E contains a detailed description of the 
format and content of an index file. 
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Figure 5-1 Directory Structure for Single-User Volumes 
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Figure 5-2 Directory Structure for Multiuser Volumes 


5.1.4 File Header Block 


Each file has a file header block that contains a description of the 
file. File header blocks are stored in the index file. Each file 
header block is 256 words long and contains the header area, the 
identification area, and the map area. 


The header area identifies the block as a file header block. Each 
file is uniquely identified by a file ID consisting of two words. FCS 
uses the first word of the file ID (that is, the file number) to 
calculate the virtual block number (VBN) of that file's header block 
in the index file. (This calculation is done as follows: the VBN is 
the file number + 2 + the number of index file bit map blocks.) The 
operating system uses the second word (that is, the file sequence 
number) to verify that the header block is really the header for the 
desired file. 


When you request file access, both the file number and the _ file 
sequence number are specified. The system denies a request for access 
if the file sequence number does not match the corresponding field in 
ca file header block that is associated with the specified file 
number. 
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When you delete a file, its file header block space becomes available 
for storing a newly created file's sequence number. If you attempt to 
access a file that has been deleted (for example, by referencing an 
obsolete directory entry), this updated file sequence number ensures 
the rejection of the request for access, even if the same file header 
block is reused for a different file. 


The identification area specifies the file's creation name and 
identifies the file owner's’ UIC. This area also specifies the 
creation date and time, the revision number, the date and time of the 
last revision, and the expiration date. 


The map area provides the information needed by the system to map 
virtual block numbers to logical block numbers. 


A checksum value is computed each time the file header block is read 
from or written to the volume, thus ensuring that the file header 
block is transferred correctly. Appendix F contains a detailed 
description of the format and content of the file header block. 


5.2 MAGNETIC TAPE FILE PROCESSING 


RSX-11M/M-PLUS and Micro/RSX systems support the’ standard ANSI 
magnetic tape structure as described in "Magnetic Tape Labels and File 
Structure for Information Interchange," ANSI X3.27-1978. Any of the 
following file/volume combinations can be used: 


e Single file on a single volume 

e Single file on more than one volume 

e Multiple files ona singie volume 

e Multiple files on more than one volume 


The second and fourth file and volume combinations constitute a volume 
set. 


The record format on magnetic tape differs from that on disk. When a 
file containing variable-length records or fixed-length records that 
cross block boundaries is copied to magnetic tape, it occupies more 
blocks on the magnetic tape than it did on the disk. This is so 
because magnetic tape record counts are larger disk record counts, and 
there is unused space at the end of the blocks. In addition, a bit is 
set in the file's FDB that indicates the file cannot cross’. block 
boundaries. 


Appendix G defines the sequence in which volume and file labels are 
used and the format of each label type. 


NOTE 


The ANSI file header label contains no place for the 
creation time or the length of the file. 
Consequently, the creation time of a file on ANSI 
magnetic tape is listed as 0. If a contiguous file is 
copied to ANSI magnetic tape and then transferred back 
to disk, the resulting disk file is not marked as 
contiguous even if you use the /CO switch, because the 
system cannot know how much space to allocate for the 
output file when it reads from magnetic tape. 
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5.2.1 Access to Magnetic Tape Volumes 


Magnetic tape is a sequential access, single-directory storage medium. 
Only one user can have access to a given volume set at a time. Only 
one file in a volume set can be open at a time. The system protects 
access by volume set rather than by file. On volumes produced by 
DIGITAL systems, the contents of the owner identification file 
determine user access rights as described in Section G.1.1.1. Volumes 
produced by non-DIGITAL systems are restricted to read-only access 
unless the access is overridden explicitly at MOUNT time. 


5.2.2 Rewinding Volume Sets 


You can rewind a magnetic tape volume set by using either the FDOPSR 
macro before an OPENS or CLOSES macro or by using the .CTRL file 
control routine. Regardless of the method you use, FCS performs these 
procedures: 


1. All mounted volumes are rewound to the beginning-of-tape 
(BOT). 


2. If the first volume in the set is not mounted, the 
device-unit to be used is placed off line. 


3. If the volume is not already mounted and if the rewind was 
requested with an OPENS macro or by a .CTRL routine call, a 
request to mount the first volume appears on the operator's 
console. 


4. If the rewind was requested with a CLOSES macro, no mount 
message is issued until the next volume is needed. 


5.2.3 Positioning to the Next File Position 


The standard procedure for writing a new file onto a magnetic tape is 
to begin writing the file following the end of the volume set's last 
file. However, you can use the FDOPSR macro to indicate that the new 
file is to be written immediately after the labels at the end of the 
most recently closed file. 


NOTE 


The next file position option causes the loss of any 
files physically following this most recently closed 
file in the volume set. 


If, in addition to the next file position option, the 
rewind option also is specified, the file is created 
after the VOL1 label on the first volume of the set. 
All files previously contained in the entire volume 
set are lost. 


To create a file in the next file position, FA.POS must be set in FDB 
location F.ACTL. The default value for this FDB position is 0 (not 
FA.POS). The default indicates that the file system is to position 
itself at the logical end of the volume set to create the file. 


When you use the default, the file system makes no check for’ the 
existence of a file with the same name in the volume set. Therefore, 
a program written to use magnetic tape normally should specify FA.POS. 
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Directory device file processors ignore the next file position option. 
However, programs written mainly for directory devices can specify the 
next file position option in open commands for output and, therefore, 
override a process of positioning the file system to the logical end 
of file normally used with ANSI magnetic tape. 


5.2.4 Single-File Operations 
You perform single-file operations by specifying the rewind option 
with the FDOPSR macro before the open and before the close. Using 
this approach, you can perform operations on temporary tapes or work 
tapes (scratch tapes) as follows: 

l. Open the first file with the rewind option specified. 

2. Write the data records and close the file with rewind. 

3. Open the first file again for input (rewinding is optional). 

4. Read and process the data. 

5. Close the file with rewind. 

6. Open the second file with rewind specified. 


7. Write the data records. 


8. Close the file with rewind and perform any additional 
processing. 


5.2.5 Multiple-File Operations 

You create a multiple-file volume by first opening, writing, and then 
closing a series of files without specifying the rewind option. You 
can process files sequentially on the volume by closing without rewind 
and opening the next file without rewind. 


Opening a file for extend with the OPENSA macro is legal only for the 
last file on the volume set. 


Perform the following tape operations to create a multiple-file tape 
volume: 


l. Open a file for output with the rewind option. 
2. Write data records and close the file. 
3. Open the next file without rewinding. 
4. Write the data records and close the file. 
5. Repeat for as many files as desired. 
You can open files on tape in a nonsequential order, but doing = so 


increases processing and tape-positioning time. Nonsequential access 
of files in a multivolume set is not recommended. 
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5.2.6 Using .CTRL 


You can call the .CTRL file control routine to override normal 


defaults for magnetic tape. This routine might be used to: 


@e Continue processing a file on the next volume of a volume 


before the end of the current volume is reached. 


e Position to the logical end-of-volume set. 


e Rewind a volume at other times than when opening or 
the file. 


@e Space forward or backward any number of records. 
e Rewind a file. 


When FCS uses the .CTRL routine to continue processing a file 


FCS 
set 
closing 
on the 


next volume, the first file section on the next volume is opened. 
volume. 
The portion of the file on each of these volumes constitutes a file 
section. For input files, the following .CTRL routine processing 


File sections occur when a file is written on more than one 


occurs: 


l. If the current volume is the last volume in the set (that is, 
there is no next volume), the end-of-file is reported to you. 


2. If another file section exists, the current volume is rewound 
and the next volume is mounted. A request to mount the next 


volume appears on the operator's console. 


3. The header label (HDR1) of the next file section is read 


checked. 


4. If all required fields check, the operation continues. 


5. If any check fails, the operator is requested to mount 


correct volume. 


For output files, the following .CTRL routine processing occurs: 


1. The current file section is closed with EOV1 and EOV2 
and the volume is rewound. 


2. The next volume is mounted. 


3. A file with the same name and the next higher section 


is opened for a write operation. The file set identifier is 


identical with the volume identifier of the first volume 


the volume set. 
NOTE 
I/O buffers that are currently in memory are written 


on the next file section. 


When the .CTRL routine positions the tape to the logical end 


and 

the 
labels 
number 
in 

of the 


volume, the file system positions the tape between the two tape marks 


at the logical end of the last volume in the set. 


When the .CTRL routine spaces forward or backward across’ blocks 


Magnetic tape, spacing crosses volumes for multivolume files. 


on 
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5.2.7 Examples of Magnetic Tape Processing 


The following sections contain examples of FCS statements that process 
magnetic tape. Macro parameters not related to magnetic tape handling 
are omitted from these statements. 


5.2.7.1 Examples of OPENSW Macro-1ll Statements to Create a New File - 
All routines expect RO to contain the FDB address. 


OPRWDO: 


OPEN WITH REWIND 


me me ™O 


FDOPSR- RO,,,,,#FA.ENB! FA.RWD ;SET REWIND AND ENABLE USE 


BR OPNOUT ;OF F.ACTL 
OPNXTO: 


OPEN FOR NEXT FILE POSITION 


me me Ne 


FDOPSR- RO,,,,,#FA.ENB! FA.POS ;SET POSITION TO NEXT 
BR OPNOUT ;AND ENABLE USE OF F.ACTL 
OPROYK: 


OPEN FILE AT END OF VOLUME KEEPING CURRENT USER 
ACCESS CONTROL BITS 


me me NO NO 


BIC #FA.ENB,F.ACTL (RO) ;DISABLE USE OF F.ACTL 
BR OPNOUT 


a 
; OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR 
; USER ACCESS CONTROL BITS 
FDOPSR- RO,,,,,#0 ;DISABLE USE OF AND RESET 
BR OPNOUT ;F.ACTL TO ZERO 


; 
; OPEN FILE WITH CURRENT USER ACCESS CONTROL 


OPOURO: 
BIS #FA.ENB,F.ACTL (RO) ;ENABLE USE OF F.ACTL 

OPNOUT: FDBFSR_ RO,,#2048. ;OVERRIDE BLOCK SIZE FOR TAPE 
OPENSW- RO 


RETURN 


5.2.7.2 Examples of OPENSR Macro-1ll Statements to Read a File - All 
routines expect RO to contain the FDB address. 


OPRWDI: 


OPEN WITH REWIND 


me we tO 


FDOPSR- RO,,,,,#FA.ENB! FA.RWD 
BR OPNIN 
OPCURI: 


OPEN STARTING SEARCH AT CURRENT TAPE POSITION KEEPING USER 
ACCESS CONTROL BITS 


me TO MO MeO 


BIC #FA.ENB,F.ACTL (RO) ;DISABLE USE OF F.ACTL 
BR OPNIN 
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OPEN USING USER ACCESS CONTROL 


e@ te we 


: : 

OPDFLI: BIS #FA.ENB,F.ACTL (RO) ;ENABLE USE OF F.ACTL 

OPNIN: FDBFSR_ RO,,#2048. ;OVERRIDE BLOCK SIZE FOR TAPE 
OPENSR- RO 
RETURN 


5.2.7.3 Examples of CLOSES Macro-ll Statements - All routines expect 
RO to contain the FDB address. 


CLSCUR: 


CLOSE LEAVING TAPE AT CURRENT POSITION AND KEEPING 
USER ACCESS CONTROL BITS 


meme TO NEO 


BIC #FA.ENB,F.ACTL (RO) ;DISABLE USE OF F.ACTL 
BR CLOSE ;DEFAULT IS LEAVING AT CURRENT 
; POSITION 


CLSRWD: 


CLOSE REWINDING THE VOLUME 


meme % 


FDOPSR_ RO,,,,,#FA.ENB! FA.RWD 7;SET REWIND AND ENABLE USE OF 
BR CLOSE 7;F.ACTL 


me 6 


CLOSE WITH USER ACCESS CONTROL BITS 


’ 
CLSDFL: BIS #FA.ENB,F.ACTL (RO) ;ENABLE USE OF F.ACTL 
CLOSE: CLOSES RO 

RETURN 


5.2.7.4 Combined Examples of OPEN$ and CLOSES Macro-ll Statements - 
The following examples call routines shown in previous examples in 
Section 5.2.7.1. By combining various magnetic tape operations, you 
can process tape volumes in the following ways: 


SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-- 


e 
tf 
e 
e 
° 
o 

iS) 


CROUT: MOV #FDBOUT ,RO ;SELECT FDB AND OPEN 
CALL OPRWDO ;OUTPUT FILE WITH REWIND 
RETURN 

SCRIN: MOV #FDBIN,RO ;SELECT FDB AND OPEN FOR 
CALL OPRWDI ; INPUT WITH REWIND 
RETURN 

CLSCRO: MOV #FDBOUT,RO ;CLOSE SCRATCH FILE 
BR CLSVOL ;REWINDING VOLUME 

CLSCRI: MOV FDBIN,RO 

CLSVOL: CALL CLSRWD 
RETURN 


MULTI-FILE VOLUME OPERATIONS 
PNXTI : 


OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME 


me we we CO we we we 


MOV #FDBIN,RO ;SELECT FDB 
CALL OPCURI ,;OPEN FILE 
RETURN 
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OPENIN: 


OPEN FILE FOR READING WHEN POSITIONED PAST IT 


me we WO 


MOV #FDBIN,RO ;SELECT FDB 
CALL OPRWDI 
RETURN 

7 

, MULTI-FILE OUTPUT OPERATIONS 

; 

OPNINT: 

7 

; START NEW VOLUME DESTROYING ALL PAST FILES ON IT 

7 
MOV #F DBOUT , RO ;SELECT OUTPUT FDB 
CALL OPRWDO ;OPEN WITH REWIND 
RETURN 


OPNEXT: 


THAT MAY BE AT OR PAST THAT POSITION 


moe ™8 we SO 


MOV #F DBOUT ,RO ;SELECT 
CALL OPNXTO 
RETURN 


OPENDT: 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET 
ACCESS CONTROL BITS 


me SO Se NO 


MOV #F DBOUT ,RO ; SELECT 
CALL OPROVK 
RETURN 


OPNEOV: 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND 
ACCESS CONTROL 


me we NSO WO 


MOV #F DBOUT ,RO ,;SELECT 
CALL OPROVO 
RETURN 


; 
; NOT LAST FILE IN FILE SET CLOSE ROUTINE 


CLSFLO: MOV #FDBOUT ,RO ;SELECT 
BR CLSXX 
CLSFLI: MOV #FDBIN,RO ;SELECT 
CLSXX: CALL CLSCUR 
RETURN 


TO APPEND TO LAST FILE 


meme we UI 


OPENSA #FDBOUT 


OPEN OUTPUT FILE AT NEXT FILE POSITION DESTROYING ANY FILE 


OUTPUT FDB 


KEEPING USER 


OUTPUT FDB 


MAKE THAT THE USER 


OUTPUT FDB 


OUTPUT FDB 


INPUT FDB 


CHAPTER 6 


COMMAND LINE PROCESSING 


This chapter describes two object library routines that are available 
from the system object library, [1,1]SYSLIB.OLB. These routines may 
be linked with your task to provide the logical capabilities necessary 
to process terminal command line input as follows: 


e Get Command Line (GCML) - This routine accomplishes all the 
logical functions associated with the entry of command lines 
from a terminal, an indirect command file, or an on-line 
storage medium. Using GCML relieves you of the burden of 
manually coding command line input operations. 


@e Command String Interpreter (CSI) - Normally, this routine 
takes command lines from the GCML command line input buffer 
and parses them into the appropriate dataset descriptors that 
FCS requires for opening files. 


The Task Builder links these routines with your program when the’ task 
is being built. GCML and CSI are often used together in system or 
application programs as a standardized interface for obtaining and 
interpreting dynamic command line input. Figure 6-1 shows the flow of 
data during command line processing. 


Although this chapter assumes the joint use of these routines’ to 
process command line input, GCML and CSI may be used independently. 
Using one without the other, however, requires that you manually code 
the functions normally performed by the missing component. 


Invoking GCML and CSI functions requires that certain initialization 
be done when you write the source code. This initialization sets up 
the GCML command line input buffer, defines and initializes control 
blocks for both GCML and CSI, and establishes the necessary working 
storage and communication areas for these routines. Also, the 
appropriate macro calls that invoke GCML and CSI execution-time 
functions must be included in the source code at appropriate logical 
points to effect the dynamic processing of command lines. 


GCML and CSI macro calls observe the same register conventions as FCS. 
All registers except RO are preserved exactly as those in FCS macro 
calls. RO contains the address of the GCML control block or the CSI 
control block, as appropriate. 


As with all FCS macro calls, the GCML and CSI macro calls must be 
listed as an argument in an .MCALL directive (see Section 2.1) before 
you insert them in your program. 
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Figure 6-1 Data Flow During Command Line Processing 


6.1 GET COMMAND LINE (GCML) ROUTINE 


The Get Command Line (GCML) routine contains all the logical 
capabilities necessary to enter command lines dynamically during 
program execution. GCML accepts input from a terminal or an indirect 
command file that contains predefined command lines. If your program 
allocates sufficient buffer space in the file storage region (see 
Section 2.6), GCML accepts commands that are longer than one line of 
terminal input. The appearance of a hyphen as the last printing 
character of a command line permits the continuation of commands from 
one line to the next. 


All GCML functions require you to create and initialize a GCML control 
block. See Section 6.1.1 for a description of this macro call. The 
GCML run-time macro calls that your task may issue dynamically are 
described in Section 6.1.3. 
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6.1.1 GCMLBS - Allocate and Initialize GCML Control Block 


This section describes the GCMLBS$ macro. This macro is a necessary 
part of the code needed to dynamically obtain and execute command 
lines. During the assembly of your program the GCMLBS macro: 


e Reserves storage for and initializes a GCML control block 
within your program. 


e Creates and initializes an FDB for the indirect command file 
in the first part of the GCML control block. 


e Creates and initializes a default filename block within the 
GCML control block. 


e Defines the symbolic offsets for the GCML control block and 
initializes certain offsets to required values by invoking the 
GCMLD$ macro. These offsets are described in detail in 
Section 6.1.2. 


FCS uses the FDB to open an indirect command file. Your program may 
open and read a command file, which can use a terminal or a 
file-structured device such as a disk. GMCL and FCS initialize and 
maintain this FDB. 


FCS uses the default filename block for an indirect command file. If 
you do not specify an explicit filename string for an indirect command 
file, the values CMI for the file name and .CMD for the file type are 
assumed by default. There is no default designation for the device 
name. 


The GCMLBS macro has the following format: 
Format 

label: GCMLBS maxd,prmpt,ubuf,lun,pdl,size 
Parameters 

label 


A symbol that names the GCML control block and defines its 
address. This label permits the GCML control block’ to be 
referenced directly by all the GCML run-time routines’ that 
require access to this structure (see Section 6.1.3). 


maxd 


A numeric value that specifies the maximum nesting depth 
permitted for indirect command files. This parameter determines 
the number of nested indirect command files that GCML can access 
in obtaining command line input. 


An indirect command file, which often resides on disk, contains 
well-defined, nonvarying command sequences, which may be read 
directly by GCML to control such highly repetitive operations as 
Task Builder activities. 


If you do not specify this parameter, the default nesting level 
depth is 0, which effectively eliminates an indirect command file 
as a source of command line input. 
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prmpt 


ubuf 


lun 


pdl 


A 3-character ASCII prompting sequence that you specify. The 
GCML routine displays this default prompt string at your terminal 
to solicit command line input. 


Construct the ASCII prompting sequence as the following 6-byte 
string: 


e A carriage return (<CR>) and a line-feed (<LF>) 
e The three ASCII characters that you specify 
e A right angle bracket (>) 


The ASCII prompting sequence initializes GCML control _ block 
offset location G.DPRM (see Section 6.1.2). 


If you do not specify this parameter, GCML uses the right angle 


bracket (>), preceded by three blanks, as the default prompting 
sequence. 


The address of a buffer that the GCML routine uses for temporary 
storage of command line input. If you do not specify this 
Parameter, a buffer is reserved in the GCML control block for 
command line input. The size parameter determines the length of 
the buffer. If you specify neither this parameter nor the size 
parameter, a 4l-word buffer is reserved by default in the GCML 
control block. 


A logical unit number. The GCML routine uses the device assigned 
to this logical unit number as the command input device. If you 
do not specify this parameter, GMCL uses a logical unit number of 
l by default. 


The address of an area reserved in your program as a _ push-down 
list. Indirect command file processing uses this area for 
working storage. Normally, you do not specify the pdl parameter 
unless you want to increase the storage for the push-down list. 


Statements logically equivalent to the following create the 
push-down list: 


- EVEN 
label: .BLKB G.LPDL 


The label that you supply specifies the push-down list and 
defines its address. G.LPDL, which is defined by the GCMLBS 
macro, is the length (in bytes) of the push-down list. 


The length of the push-down list is a function of the maximum 
number of nested indirect command files that may be accessed by 
GCML in obtaining command line input. You can increase the 
storage in the control block for the push-down list by 
calculating the value according to the following algorithm: 


1. Add 1 to the maximum nesting level depth declared with the 
maxd parameter described previously. 
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2. Multiply the sum of step 1 by 16(decimal) to find the number 
of bytes that must be reserved for the push-down list. 


For example, if you specify 4 as the maxd parameter, you 
determine the length of the push-down list as follows: 


(4+41)*16. = 80. bytes 


From the previous mathematical statement, note that 16(decimal) 
bytes of storage are required for each indirect command file (4), 
plus another 16(decimal) bytes as general overhead. 


size 


The size, in bytes, of the buffer reserved for command line 
input. The size must always include two extra bytes that are 
used internally by GCML. The default size value is 82 (that is, 
80 bytes for command line input and 2 bytes GCML overhead). 


If you want GCML to accept continuation lines, the specified 
value for the size parameter must be greater than 82. When the 
size is greater than 82, the bit value GE.CON is set in the 
Status and mode control byte (offset G.MODE) of the GCML command 
block. This value indicates that the continuation mechanism is 
in effect. 


Examples of how a GCMLBS macro call may be used in a program follow: 
GCLBLK: GCMLBS 4.,GCM,BUFADR,1. 


GCLBLK: GCMLB$ ,,BUFADR 
GCLBLK: GCMLBS DEPTH,GCM,BUFADR,CMILUN, PDLIST,BUFSIZ 


6.1.2 GCMLDS$ - Define GCML Control Block Offsets and Bit Values 


The GCMLDS macro, which the GCMLBS macro call invokes, locally defines 
the GCML control block offsets and bit values within the current 
module. A description of these offsets and their bit values follows: 


Symbolic 

Offset 
Name Description 
G.ERR Error Return Code Byte 


This field initially contains 0. If any error 
conditions that GCML recognizes occur during the 
processing of a command line, an appropriate error 
code is returned to offset location G.ERR in the 
control block. Descriptions of these error bits 
follow: 


GE.IOR - I/O error occurred during the input of 
a command line. 


GE.OPR - GCML unable to open or reopen the 
specified command file. 


GE.BIF - Syntax error detected in the name of 
the indirect command file. 


GE.MDE - Attempt made to exceed the maximum 
permissible nesting-level depth for an indirect 
command file (see the description of the maxd 
parameter in Section 6.1.1). 
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Symbolic 
Offset 
Name 


G.MODE 
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Description 


GE.RBG - Command line input buffer was too 
small for the total command. This condition 
can occur when multiple lines have been entered 
using the continuation mechanism. The input 
buffer contains as much of the command as 
possible. 


GE.EOF - End-of-file (EOF) on the top-level 
command file detected. 


NOTE 


For GE.IOR and GE.OPR, additional 
information concerning the error is 
available by examining the FCS error 
code at offset F.ERR from the start of 
the GCML block. 


The error code is set along with command file 
input. When the first call is issued for input, 
GCML attempts to retrieve an MCR command line. 


Command level O is set for the first line 
obtained, whether it is an MCR command or a 
terminal command. If the name of an indirect 


command file is then entered, the command input 
level is increased to 1. Each indirect file name 
entry thereafter increments the command input 
level. When the end-of-file (EOF) is encountered 
on any given indirect file, the command input 
level is decremented by 1, restoring the count to 
the previous level and reopening the associated 
command file. The next command line from that 
file is then read. 


If an MCR command has already been read at level 
0, entering another MCR command when level 0 is 
again reached causes the error code GE.EOF to be 
returned to offset location F.ERR of the GCML 
control block. Hence, only one MCR command line 
can be read at level 0. If input thus fails at 
MCR level 0, then GCML continues to prompt for 
input until you type CTRL/Z to indicate terminal 
end-of-file (EOF). 


In summary, the first line of input is always read 
at level 0. This initial input may be an MCR 
command; if the MCR command fails or is null, the 
command input file (normally a terminal) is then 
opened at level 0. Multiple inputs at level 0 are 
permissible only in the latter case, that is, from 
the command input file. 


Status and Mode Control Byte 
This field is initialized at assembly time with 


bit definitions to specify certain default actions 
for GCML during the retrieval of a command line. 


Symbolic 
Offset 
Name 
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Description 


At run time, you can reset default status and mode 
control bits by issuing a Bit Clear Byte (BICB) 
instruction that takes the symbolic name of the 
bit to be cleared as the source operand. In the 
case of the GE.LC value (see the following text), 
the BISB instruction can override the default 
action. 


Descriptions of the symbolic names of the bits 


defined in the status and mode control byte 
follow: 


GE.IND - (Default) A command line that begins 
with a leading at sign (@) is an explicit 
indirect command file specification. If you 
reset the GE.IND bit to 0, a command line 
beginning with an at sign (@) is returned to 
the calling program. 


GE.CLO - (Default) The command file currently 
being read is closed after each GCMLS$ macro 
call is issued. If you reset the GE.CLO bit to 
0, GCML keeps the current command file open 


between calls for input. In this case, the 
File Storage Region (FSR) described in Section 
2.6.1 must include one additional 


512 (decimal)-byte buffer for command line 
input. This requirement adds to the total FSR 
block buffer space normally reserved for the 
maximum number of files that may be open 
simultaneously for record I/O processing. 


Clearing the GE.CLO bit in the status and mode 
control byte renders 512(decimal) bytes of FSR 
block buffer space unavailable for other 
purposes, because the command file remains open 
between calls for command line input. 


GE.COM —- (Default) A command line that begins 
with a leading semicolon (;) is a comment. 
Such lines are not returned to the calling 
program. If you reset this bit to 0, a command 
line beginning with a leading semicolon (;) is 
returned to the calling program. 


GE.CON - If the value of the size parameter of 
the GCMLBS$ macro is greater than 82, the 
continuation mechanism is in effect by default. 
You must not attempt to set this bit in the 
mode byte without providing a buffer larger 
than 82 bytes. 


GE.LC - If this bit is set to 1 in the GCML 
control block at run time, lowercase characters 
in the command line are passed unaltered to 
your program. If this bit is not set, 
lowercase characters are changed to upppercase 
before being passed to your program. 


Symbolic 
Offset 
Name 


G.PSDS 


G.CMLD 


G.ISIZ 
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Description 
Prompt String Descriptor 


This 2-word field is initialized at assembly time 
to 0 by issuing the GCMLBS$ macro call (see Section 
6.1.1). 


When you issue the GCML$ macro call to request 
command line input (see Section 6.1.3.1), the 
address and the length of a prompting sequence are 
usually not specified. In this case, the prompt 
string descriptor words in the GCML control block 
are cleared, causing GCML to type out the default 
prompt string contained in offset location G.DPRM 
to solicit command line input. (See the 
description of G.DPRM in the following text.) 


If you want to define an alternate prompt’ string 
elsewhere in the program, you may do so through 
the .ASCII directive. The address and length of 
this alternate prompt string may then be specified 
as the adpr and Inpr parameters in subsequent 
GCML$ macro calls. (See the description of these 
Parameters and how they affect alternate prompt 
strings in the following text.) These parameters 
cause offset locations G.PSDS+2 and G.PSDS to _ be 
initialized with the address and the length, 
respectively, of the alternate prompt. string. 
GCML then types out the alternate prompt string to 
solicit command line input, thereby overriding the 
default prompt string previously established 
through the GCMLBS macro call. 


If you do not specify the adpr and lnpr parameters 
in a subsequent GCMLS$ macro call, offset location 
G.PSDS in the control block is reset to 0, causing 
GCML to revert to the use of the default prompt 
string contained in offset location G.DPRM. 


Command Line Descriptor 


GCML initializes this 2-word field after 
retrieving a command line. fThe address of this 
command line is returned to offset location 
G.CMLD+2, and the length (in bytes) of the command 
line is returned to offset location G.CMLD. 


The contents of these word locations in the GCML 
control block may be passed to CSI as the buff and 
len parameters in the CSIS$1 macro call (see 
Section Ose 36) The combination of these 
parameters constitutes the command line 
descriptors that enable CSI to retrieve file 
specifications from the GCML command line input 
buffer. 


Impure Area Size Indicator 
This symbol is defined at assembly time, 


indicating the size of an impure area within the 
GCML control block to be used as working storage 
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Symbolic 
Offset 
Name Description 


for pointers, flags, counters, and so forth, along 
with input from an indirect command file. In 
normal usage, you need not be concerned with this 
symbol. 


The space between the FDB and the default prompt 
string (see G.DPRM in the following text) is the 
impure area of the GCML control block. The value 
of the symbol S.FDB defines the size of the FDB. 
Thus, the size of the impure area is equal to 
G.DPRM minus S.FDB (G.DPRM-S.FDB). 


G.DPRM Default Prompt String 


This 6-byte field is initialized at assembly time 
with the default prompt string created through the 
prmpt parameter of the GCMLBS macro call (see 
Section 6.1.1). In the absence of the adpr and 
lnpr parameters in the GCMLS macro call (see 
Section 6.1.3.1), GMCL types out this default 
prompt string to solicit terminal input. 


You can reference the GCML control block offsets and bit values in 
another module by establishing the appropriate symbolic definitions 
within that module through one of the following statements: 


GCMLDS ;DEFAULT LOCAL DEFINITION 
GCMLD$ DEFSL ;LOCAL DEFINITION 
GCMLD$ DEFSG ;GLOBAL DEFINITION 


6.1.3 GCML Routine Run-Time Macros 


GCML provides the following three run-time macro calls to perform 
specific functions: 


GCMLS$ - Retrieves a command line 


RCMLS - Resets the indirect command file scan to the first 
(unnested) level 


CCMLS$ - Closes the current command file 


These routines are described in the following sections. 


6.1.3.1 GCML$ - Get Command Line Macro - GCMLS$ serves as your program 
interface for retrieving command lines from a terminal or an indirect 
command file. You can issue this macro call at any logical point in 
the program to solicit command line input. 

This macro call has the following format: 

Format 


GCMLS gclblk,adpr,lnpr 
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Parameters 


gclblk 


adpr 


lnpr 


The address of the GCML control block. This symbol must be the 
same as that specified at assembly time in the label field of the 
GCMLBS$ macro call (see Section 6.1.1). If you do not’ specify 
this parameter, RO is assumed to contain the address of the GCML 
control block. 


The address of your program location containing an alternate 
prompt string. When this optional parameter and the Inpr 
parameter following are present in the GCMLS macro call, the 
alternate prompt string appears on your’ terminal to solicit 
command line input. The normal default prompt string, as 
contained in offset location G.DPRM of the GCML control block 
(see Section 6.1.2), is thereby overridden. 


The length (in bytes) of the optional, alternate prompt string. 
If you do not specify this parameter, offset location G.PSDS in 
the GCML control block (see Section 6.1.2) is cleared. 


If you specify this parameter, but do not specify the adpr 
parameter described previously, an .ERROR directive is generated 
during assembly that causes the error message PROMPT STRING 
MISSING to be printed in the assembly listing. This message is a 
diagnostic announcement of an incomplete prompt string descriptor 
in the GCML$ macro call. If you specify this parameter, as well 
as the adpr parameter, the default prompt string is used. 


If you do not specify the adpr and Inpr parameters in a_ subsequent 
GCMLS$ macro call, offset location G.PSDS in the GCML control block is 
reset to 0. Consequently, GCML reverts to using the default prompt 
string contained in offset location G.DPRM (see Section 6.1.2). 


When 


you issue the GCMLS macro call, the following occurs: 


1. RO is loaded with the address of the GCML control block. If 
you do not specify the gclblk parameter, RO is assumed to 
contain the address of the GCML control block. If it does 
not contain that address, you must first manually initialize 
RO with the address of the control block before you issue the 
GCMLS$ macro call. 


2. The address and the length of the alternate prompt string, if 
specified, are stored in control block offset locations 
G.PSDS+2 and G.PSDS, respectively. These two words 
constitute the alternate prompt string descriptor. 


3. Code is generated that calls GCML to transfer a command line 
to the command line input buffer. If the last character of 
an input line is a hyphen, and if the value GE.CON is present 
in the status and mode control byte, GCML transfers commands 
that are longer than one line. The continuation lines 
obtained are concatenated in the input buffer with the 
continuation hyphen(s) removed. 
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When your task first issues the GCML$ macro call, GCML$ tries to 
retrieve an MCR command line. If this attempt fails, or if the MCR 
command line is null, GCML uses the FDB within the GCML control block 
to open a file for command line input. If the command input device is 
a terminal, a prompt string appears on your terminal to solicit input. 
Any appropriate command input may then be entered. If the 
continuation mechanism is in effect, the prompt string reappears’ to 
solicit subsequent portions of the continued command line. 


If appropriate, you may enter an at sign (@) as the first character in 
the command line, followed by the name of an indirect command file. 
This file name identifies an explicit indirect command file from which 
input is to be read. GCML then opens this file and retrieves the 
first command line. On successive GCML calls, this file is read until 
one of the following occurs: 


e The end-of-file (EOF) is detected on the current indirect 
file. In this case, the current indirect file is closed, the 
command input level count is reduced by 1, and the previous 
command file is reopened. If the command input level count is 
already 0 when EOF is detected, the error code GE.EOF is 
returned to offset location G.ERR of the GCML control block 
(see Section 6.1.2). 


e An indirect file specification is encountered in a _ command 
line. In this case, the current indirect command file is 
closed (if not already closed), the new indirect file is 
opened, and the first command line is read. 


@ An RCMLS macro call is issued in the program (see Section 
6.1.3.2). In this case, the current indirect command file is 
closed, and the command input count reverts to level 0; that 
is, the top-level command file is again used for input. 


You may also enter a semicolon (;) as the first character in the 
command line. If GE.COM is set, such a line is treated as a comment 
and is not returned to the calling program. If GE.COM is clear, the 
line is returned to the calling program. 


Whether a command line is entered manually or retrieved from an 
indirect command file, the address and the length of the command line 
are returned to GCML control block offset locations G.CMLD+2 and 
G.CMLD, respectively. Together, these two words constitute the 
command line descriptors. These descriptors may be specified as _ the 
buff and len parameters in the CSI$1 macro (see Section 6.2.3.1). 


Successful retrieval of a command line causes the Carry bit in the 
Processor Status Word to be cleared. Any error condition that occurs 
during the retrieval of a command line, however, causes the Carry bit 
to be set. In addition, a negative error code is returned to offset 
location G.ERR of the GCML control block. These error codes’ are 
described in detail in Section 6.1.2. 


Examples of how you may use the GCMLS$ macro in a program follow: 
GCMLS$ #GCLBLK 
GCML$ 


GCMLS$ #GCLBLK, #ADPR, #LNPR 
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The first example specifies the symbolic address of the GCML control 
block. The second example assumes that RO contains the address of the 
GCML control block. Both these forms of the GCML$ macro employ’ the 
default prompt string contained in offset location G.DPRM of the 
control block to solicit command line input. The last example 
specifies the address and the length of an alternate prompt string 
that you have defined within the program. GCML uses this alternate 
prompt string to prompt for terminal input, rather than using the 
default prompt string contained in the GCML control block. 


6.1.3.2 RCML$ - Reset Indirect Command File Scan Macro - If you must 
close the current indirect command file and return to the top-level 
file, that is, to the top-level (unnested) file, you may do so _ by 
issuing the RCMLS macro. 
You specify the RCMLS$ macro in the following format: 
Format 
RCMLS gclblk 
Parameter 
gcliblk 
The address of the GCML control block. If you do not’ specify 
this parameter, RO is assumed to contain the address of the GCML 


control block. 


When you issue this macro, the current indirect command file is 


closed, returning control to the top-level (unnested) file. A 
subsequent GCMLS$ macro then retrieves the next command line from the 
O-level command file. Note, however, that a second MCR command at 


level O cannot be read (see GE.EOF error code in offset location G.ERR 
of GCML control block, Section 6.1.2). 


Examples of how you may use the RCMLS macro in a program follow: 
RCMLS$ #GCLBLK 
RCMLS RO 


This macro call requires only the address of the GCML control block. 


6.1.3.3 CCML$ - Close Current Command File Macro - You may want to 
close the current command file between calls for input to free FSR 
block buffer space for some other use. FCS normally closes’ the 
command file after the retrieval of a command line, provided that the 
GE.CLO bit in the status and mode control byte remains appropriately 
initialized (see Section 6.1.2). This bit is set to 1 at assembly 
time. If you reset this bit to 0, the current command file remains 
open between calls for input. 


For a program that frequently reads command files, this may be a 
desirable operational mode, because keeping the file open between 
calls for input reduces total file access time. However, should you 
want to close such a file to free FSR block buffer space, you may do 
so by issuing the CCMLS macro call. 
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The CCMLS macro call has the following format: 
Format 
CCMLS gclblk 
Parameter 
gclblk 


The address of the GCML control block. If you do not’ specify 
this parameter, RO is assumed to contain the address of the GCML 
control block. 


Issuing this statement closes the current command file, effectively 
releasing 512(decimal) bytes of FSR block buffer space for some other 
use between calls for input. If the command file is already closed 
when your task issues the CCMLS macro call, control is returned to 
your task. A subsequent GCMLS macro call then causes the command file 
to be reopened and the next command line in the file to be returned to 
the calling program. 


Examples of how the CCMLS macro may be used in a program follow: 
CCML$ #GCLBLK 


CCMLS RO 


As in the RCMLS macro call described previously, this macro call takes 
a single parameter, specifically, the address of the GCML control 
block. 


6.1.4 GCML Usage Considerations 


As noted in Section 6.1.1, the GCMLBS macro call creates an FDB in the 
first part of the GCML control block. Although ordinarily you need 
not manipulate this FDB (because it is under GCML and FCS control), 
you can perform the following operations on this FDB: 


l. In an unrecoverable error situation, you can issue a CLOSES 
macro call (see Section 3.8) with the address of this FDB 
before issuing the system EXITS macro call. 


2. You can test the FD.TTY bit in the device characteristics 
byte (offset location F.RCTL) of the FDB to determine whether 
the command line just obtained was retrieved from a terminal. 


3. In the event that error code GE.IOR or GE.OPR is returned to 
control block offset location G.ERR (indicating that an I/0 
error has occurred during the retrieval of a command line), 
you can test offset location F.ERR of the associated FDB for 
a more complete error analysis. This FDB cell also contains 
an error code that may be helpful in determining the nature 
of the error condition. 


At task-build time, the Task Builder device assignment (ASG) option 
should be issued to assign the appropriate physical device unit to the 
desired logical unit number. For example, to assign the logical unit 
number (lun parameter) in the GCMLBS$ macro call (see Section 6.1.1) to 
a terminal, the following Task Builder option should be issued: 


ASG = TI:1 
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The designation TI: is a pseudo-device name that is redirected to the 


command input device. Note that the numeric value following the colon 
(:) must agree with the numeric value specified as the lun parameter 
in the GCMLBS$ macro call. 


The ASG option is described in further detail in the RSX-11M/M-PLUS 
and Micro/RSX Task Builder Reference Manual. 


LT 


As covered in the Section 2.6.1 discussion on FSRSZ$, at any given 
time there must be an FSR block buffer available for each file 
currently open for record I/O operations. You must consider’ the 
buffer requirements of the command file when issuing the FSRSZ$ macro 
(FSRSZS must be issued with a nonzero first parameter). 


6.2 COMMAND STRING INTERPRETER (CSI) ROUTINE 
The Command String Interpreter (CSI) routine analyzes command lines 
and parses them into their component device name, directory, and 
filename strings. You should be aware that CSI processes command 
lines in the following formats only: 

e dev:[g,m] outputfilespec/switch 


More than one file specification can be specified by 
separating them with commas. 


e dev:{[{g,m] outputfilespec/switch,...= dev: [g,m] 
inputfilespec/switch,... 


A file specification may be either of the following: 
filename.type;version 
or 
"ANSI name string"; version 
CSI maintains a dataset descriptor within the CSI control block (see 
Section 6.2.1), which FCS may use in opening files. The run-time 
routines that analyze and parse command lines for your calling program 
are described in Section 6.2.3. 
Using CSI requires that the CSI control block offsets and bit values 
be defined and that a control block be allocated within the program. 


The macro described in the following section accomplishes’ these 
requisite actions. 


6.2.1 CSI$ - Define CSI Control Block Offsets and Bit Values Macro 


Following is the only initialization coding required for CSI at 
assembly time: 


CSIS$ ;DEFINES CSI CONTROL BLOCK OFFSETS 
;AND BIT VALUES LOCALLY 
- EVEN ;WORD ALIGNS CSI CONTROL BLOCK 
CSIBLK: .BLKB C.SIZE ;NAMES CSI CONTROL BLOCK AND 
. ;ALLOCATES REQUIRED STORAGE 
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The CSI$ macro does not generate any executable code. The CSI control 
block resulting from the .BLKB directive allows communication between 
CSI and the calling program. The symbol C.SIZE specifies the length 
of the control block. C.SIZE is defined during the expansion of the 
CSI$ macro. Expanding this macro also causes a local definition of 
the symbolic offsets and bit values within the CSI control block. 


You can cause the control block offsets to be defined globally within 
the current module. This is done by specifying DEFSG as an argument 
in the CSIS initialization macro call, as follows: 


CSI$ DEFSG 


6.2.2 CSI$ Macro Control Block Offset and Bit Value Definitions 


The CSI$ macro locally defines the following symbolic offsets and bit 
values within the CSI control block: 


Symbolic 
Offset 
Name Description 
C.TYPR Command String Request Type 
This byte field indicates which type of file 
specification is being requested. Depending on 
whether an input or output file specification is 
being requested (see the io parameter in the CSI$2 
macro call described in Section 6.2.3.2), the 
corresponding bit in this byte is set. The bit 
definitions for this byte are as follows: 
CS.INP - Indicates that an input file 
specification is being requested. 
CS.OUT - Indicates that an output file 
specification is being requested. 
C.STAT Command String Request Status 


This byte field reflects the status of the current 
command line request. The bits in this field are 
initialized according to the following bit 
definitions: 


CS.EQU - Indicates that an equal sign (=) has 
been detected in the current command line, 
signifying that the command line contains both 
output and input file specifications. Once 
CS.EQU is set, CSI1l and CSI2 processing 
preserve the value of CS.EQU. 


CS.NMF - Indicates that the current file 
specification contains a filename’ string. 
Accordingly, control block offset locations 
C.FILD+2 and C.FILD (see the entry for C.FILD) 
are initialized with the address and the length 


Symbolic 
Offset 
Name 


C.CMLD 
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Description 


(in bytes), respectively, of the command line 
segment that contains the filename string. If no 
filename string is present, this bit is not set, 
and the filename string descriptors in the control 
block are cleared. 


CS.DIF - Indicates that the current file 
specification contains a directory string. Thus, 
control block offset locations C.DIRD+2 and C.DIRD 
(see the description following for C.DIRD) are 
initialized with the address and the length (in 
bytes), respectively, of the command line segment 
that contains the directory string. If no 
directory string is present, this bit is not set. 
In this case, any residual nonzero values in the 
directory string descriptor cells that pertain to 
a previous command string request of similar type 
are used by default (see the description of 
C.TYPR). Thus, FCS uses the last directory string 
encountered in a file specification. 


CS.DVF - Indicates that the current file 
specification contains a device name string. 
Similarly, control block offset locations C.DEVD+2 
and C.DEVD (see the description of C.DEVD) are 
initialized with the address and the length (in 
bytes), respectively, of the device name string. 
If no device name string is present, this bit is 
not set. Like CS.DIF (see the previous 
description of CS.DIF), any residual nonzero 
values in the device name descriptor cells that 
pertain to a previous command string request of 
similar type are used by default. Thus, the last 
device name string encountered in a file 
specification is used. 


CS.WLD - Indicates that the current file 
specification contains an asterisk (*), signaling 
the presence of a wildcard specification. 


CS.MOR - Indicates that the current file 
specification is terminated by a comma (,), which 
indicates that more file specifications are _ to 
follow. If this bit is not set, it signifies that 
the end of the input or output file specification 
has been reached. 


Command Line Descriptor 


This 2-word field is initialized with the length 
(in bytes) and the address, respectively, of the 
compressed command line. In other words, the 
values returned to these cells are the CSI output 
after it scans a file specification and removes 
all nonsignificant characters from the string 
(that is, nulls, unquoted blanks and tabs, and 
RUBOUTS). 


Symbolic 
Offset 
Name 


C.DSDS 


C.DEVD 


C.DIRD 


C.FILD 
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Description 


CSI uses the values contained in these cells as 
the descriptors of the compressed command line to 
be parsed (see CSI$2 macro call in Section 
6.26 See) < 


Dataset Descriptor Pointer 


This pointer defines the address of the 6-word 
dataset descriptor in the CSI control block. This 
structure is functionally identical to the 
manually created dataset descriptor detailed in 
Section 2.4.1. 


You can use this symbol to initialize offset 
location F.DSPT in the FDB associated with the 
file to be processed. Thus, FCS is able to 
retrieve the ASCII information from this structure 
that it needs to open files. 


Assembly-time initialization of F.DSPT in the 
associated FDB may be accomplished as follows: 


FDOPSA 1,CSIBLK+C.DSDS 


where CSIBLK is the address of the CSI control 
block, and C.DSDS represents the beginning address 
of the descriptor strings in the CSI control block 
(see the following entries for offset names) 
identifying the requisite ASCII filename 
information. 


Run-time initialization of F.DSPT in the 
associated FDB may also be accomplished by using 
the dspt parameter of the FDOPSR macro call (see 
Section 2.2.2) or the generalized OPENSx macro 
call (see Section 3.1). 


Device Name String Descriptor 


This 2-word field contains the address (C.DEVD+2) 
and the length in bytes (C.DEVD) of the most 
recent device name string (of those with the same 
request type) encountered in a file specification. 
Note that the colon that follows the device name 
is not included in the device name string. 


Directory String Descriptor 


This 2-word field contains the address (C.DIRD+2) 
and the length in bytes (C.DIRD) of the most 
recent directory string (of those with the same 
request type) encountered in a file specification. 


Filename String Descriptor 
This 2-word field contains the address (C.FILD+2) 


and the length in bytes (C.FILD) of the filename 
string in the current file specification. 


Symbolic 
Offset 
Name 


C.SWAD 


C.MKW1l 


C.MKW2 


C.SIZE 


C.EXPS 
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Description 


If an error condition is detected by the command 
syntax analyzer during the syntactical analysis of 
a command line (see Section 6.2.3.1), a segment 
descriptor is returned to this field, defining the 
address and the length of the command line segment 
in error. 


Current Switch Table Address 


This word location contains the address of the 
switch descriptor table specified in the current 
CSI$2 macro call (see Section 6.2.3.2). 


CSI Mask Word 1 


This word indicates’ the particular switches 
present in the current file specification after 
each invocation of the CSI$2 macro call. The 
switch mask for each of the defined switches 
encountered ina file specification between 
delimiting commas’ is inserted into this location 
by a logical OR operation. 


The mask for a switch is specified in the CSISSW 
macro call (see Section 6.2.4.1). When a switch 
is encountered in a file specification for which a 
defined mask exists, the corresponding bits in 
C.MKWl are set. By testing C.MKWl, you can 
determine the particular combination of defined 
switches present in the current file 
specification. 


CSI Mask Word 2 


This word provides you with an indication of 
switch polarity. 


When a switch is present in a file specification 
and you do not negate that switch, the defined 
mask for that switch is inserted into C.MKW2 by a 
logical OR operation in the same manner as 
described previously for C.MKWl. Conversely, when 
a switch is present in a file specifier and you do 
negate that switch, the corresponding bits in 
C.MKW2 are cleared. Thus, you can check the 
polarity of each switch that C.MKWl indicates is 
present by examining the corresponding bits in 
C.MKW2. 


Control Block Size Indicator 


This symbol, which is defined during the expansion 
of the CSIS$ macro, represents the size in bytes of 
the CSI control block. 


User Task Expansion Buffer Size 


This symbol is the constant for your’ task's 
expansion buffer size (for logical name 
expansion). It is currently set to 48(decimal). 
See the description of the CSIS$4 routine in 
Section 6.2.3.3 for more information. 
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6.2.3 CSI Run-Time Macros 


Three run-time macro calls in CSI invoke routines that perform the 
following functions: 


CSI$1 - Initializes the CSI control block, analyzes the command 
line (normally contained in the GCML command line input 
buffer), removes nonsignificant characters from the 
line, and checks it for syntactic validity. This macro 
also initializes certain cells in the CSI control block 
with the address and the length, respectively, of the 
validated and compressed command line. 


CSI$2 - Parses a file specification in the validated and 
compressed command line into its component device name, 
directory, and filename strings, and processes any 
associated switches and accompanying switch values. In 
addition, certain cells in the CSI control block are 
initialized with the appropriate string descriptors for 
subsequent use by FCS in opening the specified file. 


CSI$4 - Expands a file specification and returns a dataset 
descriptor and flag word that refer to this expanded 
file specification. The file specification string is 
not expanded into the original buffer but into a 
separate buffer in the file storage region. The use of 
CSIS$4 is recommended when parsing logical file 
specification strings. 


6.2.3.1 CSI$1 - Command Syntax Analyzer - The CSI$l1 macro invokes a 
routine called the command syntax analyzer. This routine analyzes a 
command line, which is normally read into the GCML command line input 
buffer, and checks it for correct syntax. In addition, it compresses 
the file specifications in the command line by removing all 
nonsignificant characters (that is, null, RUBOUT, and unquoted tabs 
and blanks). Finally, the command syntax analyzer initializes offset 
locations C.CMLD+2 and C.CMLD in the CSI control block (see Section 
6.2.2) with the address and the length (in bytes), respectively, of 
the validated and compressed command line. Each file specification in 
the command line is then parsed into its component device name, 
directory, and filename strings during each successive time the CSIS$2 
macro call is issued (see Section 6.2.3.2). 


The CSI$1 macro call has the following format: 

Format 
CSIS$1 csiblk,buff,len 

Parameters 

csiblk 
The address of the CSI control block. If you do not specify this 
parameter, RO is assumed to contain the address of the CSI 


control block. 


buff 


The address of a command line input buffer. This parameter 
initializes CSI control block offset location C.CMLD+2, enabling 
CSI to retrieve the current command line from a command line 
input buffer. 
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If you do not specify this parameter, you must manually 
initialize CSI control block offset location C.CMLD+2 with the 
address of a command line input buffer before issuing the CSI$1 
macro call. The following statement shows one way to manually 
initialize this location: 


MOV GCLBLK+G.CMLD+2,CSIBLK+C.CMLD+2 


len 


The length of the command line input buffer. Similarly, this 
parameter initializes CSI control block offset location C.CMLD, 
thus completing the 2-word descriptor that enables CSI to 
retrieve the current command line from the input buffer. 


As with the buff parameter described previously, if you do not 
specify this parameter, you must manually initialize CSI control 
block offset location C.CMLD with the length of the command line 
input buffer before issuing the CSI$1 macro call. The following 
statement shows one way to manually initialize this location: 


MOV GCLBLK+G.CMLD,CSIBLK+C.CMLD 


The combination of the buff and len parameters described previously 
enables CSI to analyze the scurrent command line. Following the 
analysis of the command line, CSI updates offset location C.CMLD with 
the length of the validated and compressed command line. 


If a syntactical error is detected during the validation of the 
command line, the Carry bit in the Processor Status Word is set, and 
offset locations C.FILD+2 and C.FILD in the CSI control block (see 
Section 6.2.2) are set to values that define the address and the 
length, respectively, of the command line segment in error. 


Examples of how the CSI$1 macro call may be used in a program follow: 


CSIS$1 #CSIBLK, #BUFF, #LEN 
CSIS1 RO, GCLBLK+G.CMLD+2, GCLBLK+G.CMLD 
CSI$l #CSIBLK 


The first example shows symbols that represent the address and _ the 
length of a command line to be analyzed (not necessarily the line 
contained in the GCML command line input buffer). 


The second example assumes that RO has been preset with the address of 
the CSI control block; the next two parameters are direct references 
to the command line descriptor words in the GCML control block. 


The third example assumes that the required descriptor values are 
already present in offset locations C.CMLD+2 and C.CMLD of the control 
block (CSIBLK) as the result of prior action. 


6.2.3.2 CSI$2 - Command Semantic Parser Macro - The CSI$2 macro 
invokes the command semantic parser. This routine uses the values in 
CSI control block offset locations C.CMLD+2 and C.CMLD as the address 
and the length, respectively, of the command line to be parsed. The 
routine then parses the referenced line into its component device 
name, directory, and filename’ strings. The equal sign (=) in the 
command line indicates that the string that follows is an input file 
specification. In addition, 2-word descriptors for these strings are 
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stored in a 6-word dataset descriptor in the CSI control block, 
beginning at offset location C.DSDS (see Section 6.2.2). This field 
is functionally equivalent to the dataset descriptor created manually 
in your program (see Section 2.4.1). 


The parser also decodes any switches and associated switch values 
present in a file specification, provided that the address of the 
appropriate switch descriptor table has been specified in the CSIS$2 
macro call (see the following text). The CSI switch definition macro 
calls are described in detail in Section 6.2.4. 


The CSI$2 macro call has the following format: 
Format 
CSI$2 csiblk,io,swtab 
Parameters 
csiblk 


The address of the CSI control block. If you do not specify this 
parameter, RO is assumed to contain the address of the CSI 
control block. 


io 


A symbol that identifies the type of file specification to be 
parsed. You may specify either of the following two symbolic 
arguments in this parameter field: 


INPUT - The next input file specification in the command line 
is to be parsed. 


OUTPUT - The next output file specification in the command 
line is to be parsed. 


You must initialize offset location C.TYPR in the CSI control 
block (see Section 6.2.2), either manually or through the CSI$2 
macro call, with the type of file specification being requested. 
If arguments other than the symbolic arguments defined previously 
are specified in the CSI$2 macro call, an .ERROR directive is 
generated during assembly that causes the error message INCORRECT 
REQUEST TO .CSI2 to be printed in the assembly listing. This 
diagnostic message alerts you to the presence of an invalid io 
parameter in the CSI$2 macro call. 


swtab 


The address of the associated switch descriptor table. You 
specify this optional parameter only if you suspect that the file 
specification contains a switch to be decoded. For you to 
specify this parameter, the program must already contain a switch 
descriptor table, which you created with the CSISSW macro (see 
Section 6.2.4.1). In addition, if the switch to be decoded has 
any associated switch values, the program must already contain an 
associated switch value descriptor table, which you create with 
the CSISSV macro call (see Section 6.2.4.2). 


This parameter initializes offset location C.SWAD in the CSI 
control block (see Section 6.2.2). If you do not specify this 
parameter, FCS uses any residual nonzero value in this cell by 
default as the switch descriptor table address. 
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You can also initialize offset location C.SWAD manually prior to 


issuing the CSI$2 macro call, as shown in the following 
statement: 


MOV #SWTAB,CSIBLK+C.SWAD 


where SWTAB is the symbolic address of the associated switch 
descriptor table. (The switch table must be aligned on an even 
address.) 


If an error condition occurs during the parsing of the file 
specification, the Carry bit in the Processor Status Word is set, and 
control is returned to the calling program. The possible error 
conditions that may occur during command line parsing include the 
following: 


e The request type is invalid; that is, offset location C.TYPR 
in the CSI control block (see Section 6.2.2) is incorrectly 
initialized. 


e The file specification contains a switch, but the address of 
the switch descriptor table is not specified in the CSI$2 
macro call, or the switch descriptor table does not contain a 
corresponding entry for the switch. 


e The file specification contains an invalid switch value. 


e The number of values accompanying a given switch in the file 
specification are greater than the number of corresponding 
entries in the switch value descriptor table for decoding 
those values. 


@e The file specification contains a negative switch, but the 
corresponding entry in the switch descriptor table prevents 
you from negating the switch (see the nflag parameter of the 
CSISSW macro call in Section 6.2.3.3). 


Examples of how the CSI$2 macro may be used in a program follow: 
CSIS$2 #CSIBLK, INPUT, #SWTBL 
CSI$2 RO, OUTPUT, #SWTBL 
CSIS$2 #CSIBLK, INPUT 


The first example shows a _ request’ to parse an input file 
specification, which may include an associated switch. The second 
example, which assumes that RO presently contains the address of the 
CSI control block, parses an output file specification, which also may 
include a switch. The last example is a request to parse an input 
file specification and to disallow any accompanying switches. 


6.2.3.3 CSI$4 ~ Command Semantic Parser Macro - Use CSI$4 in the same 
way that you use CSI$2. However, CSI$4 is the preferred method of 
Parsing logical names. Using CSI$4 causes the same function as CSI$2 
except that CSI$4 allows all tasks to use logical names correctly, 
except under the following two conditions: 


1. The task saves the dataset descriptor for one call to CSI$2 
and then calls CSI$2 again, expecting to be able to use the 
first dataset descriptor at a later time. 


2. The task assumes that the dataset descriptor points into’ the 
original string. 
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CSI$4 cannot be called repeatedly using the previous Dataset 
Descriptor. The reason is that whenever a parse is done, whether by 
the .PARSE routine (see Section 4.7.1), or the CSIS$4 macro, or the 
-EXPLG routine, the expanded string is always put into the FSR area of 
the task. If your task repeatedly calls CSI$4, each call overwrites 
the previous call. CSI$4 uses this common buffer for input file 
specifications, but uses a separate expansion buffer for output file 
specifications. This permits CSIS$4 to process input and output file 
specifications simultaneously. 


To allow multiple calls to CSI$4, another parameter is added to the 
CSI macro, so that: 


CS1I$2 #CSIBLK, INPUT, #CSISWT 
is changed to: 
CSI$4 #CSIBLK, INPUT, #CSISWT , #DSCBLK 


The DSCBLK parameter is a pointer to a 2-word descriptor block that 
specifies the expanded command line buffer. The descriptor block 
contains the following two words: 


WORD 0: Contains the size of the expanded command line buffer 
WORD 1: Contains the address of the expanded command line buffer 


The descriptor block and the command line expansion buffer are 
allocated in your task's address space. The size of the expansion 
buffer should be as large as any possible single file specification. 
Therefore, C.EXPS, currently set to 48(decimal), should be used. If 
the buffer is too small, an error is returned. If either value in the 
descriptor block is 0, the expansion area in the FSR is used. 


Logical name expansion requires a relatively large amount of system 
overhead. These steps should be followed to reduce the overhead 
demand: 


1. Do not change CSI$2 macros to CSI$4 macros when you want your 
task to only scan the line for switches or files without 
opening any files found. In this case, changing CSIS$2 to 
CSIS$4 only adds to the extra translation required. 


2. Include the following line before any call to .PARSE: 
BISB #FL.AEX,F.FLG(RO) ;RO is the FDB address 


This code line informs .PARSE that the string has already 
been expanded and .PARSE need not repeat the expansion. 


6.2.4 CSI Switch Definition Macros 


The following macro calls create the requisite switch descriptor 


tables in your program for processing switches that appear ina file 
specification: 


CSISSW - Creates an entry in the switch descriptor table for a 
particular switch that you expect to encounter in a file 
specification. 


CSISSV - Creates a matching entry in the switch value descriptor 
table for the switch defined through the CSISSW macro. 
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CSISND - Terminates a switch descriptor table or a switch value 
descriptor table created through the CSISSW or the 
CSISSV macro call, respectively. 


These macro calls are described in the following sections. 


6.2.4.1 CSISSW - Create Switch Descriptor Table Entry Macro - You 
must define a matching entry in the switch descriptor table for each 
switch that you expect your task to encounter in a file specification. 
If no switch descriptor table is specified or no corresponding entry 
exists, the presence of a switch in the command line causes an error. 
When your task issues a CSI$2 macro (see Section 6.2.3.2) and the 
address of a switch descriptor table is specified, the following 
processing occurs: 


1. For each switch encountered in a file specification, CSI 
searches the switch descriptor table for a matching entry. 
If either the switch descriptor table address is not 
specified, or a matching switch entry is not found in the 
table, that switch is considered invalid. As a result, the 
Carry bit in the Processor Status Word is set, any remaining 
switches in the file specification are bypassed, and control 
is returned to the calling program. 


2. If a matching entry is found in the switch descriptor table, 
mask word 1 in the CSI control block is set according to the 
defined mask for that switch (see C.MKWl, Section 6.2.2). 


3. The negation status of the switch is determined. If you do 
not negate the switch, the corresponding bits in mask word 2 
(C.MKW2) in the CSI control block are set according to the 
defined mask for that switch. If you negate the switch but 
negation is not allowed, the switch is considered invalid. 
In this case, the error sequence described in step 1 would 
occur. However, if you negate the switch, and negation is 
allowed, the corresponding bits in C.MKW2 are cleared. 


The negation flag for a switch is established through the 
nflag parameter of the CSISSW macro (described in the 
following text). 


4. If the optional mask word address is not present in the 
corresponding switch descriptor table entry, that is, if you 
did not specify the mkw parameter in the associated CSISSW 
macro, Switch processing continues with step 7. If, however, 
you did specify the optional mask word address, switch 
processing continues with step 5. 


5. If SET has been specified as the clear/set flag in the 
corresponding switch descriptor table entry, and the switch 
is not negated, then the corresponding bits in the optional 
mask word are set according to the defined mask for that 
switch. If, however, you negate the switch, the 
corresponding bits in the optional mask word are cleared. 


You specify the clear/set flag as the csflg parameter in the 
CSISSW macro. 


6. If CLEAR has been specified as the clear/set flag in the 
corresponding switch descriptor table entry, and the switch 
is not negated, the corresponding bits in the optional mask 
word are cleared. Conversely, if you negate the switch, the 
corresponding bits in the optional mask word are set. 
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7. If a switch value accompanies a switch in a file 
specification, FCS uses the associated switch value 
descriptor table created through the CSISSV macro call (see 
Section 6.2.4.2) to decode the value. There must be at least 
as many entries in the switch value descriptor table as there 
are such values accompanying the switch in the file 
specification. If the switch value descriptor table is 
incomplete, or an invalid switch value is encountered, or the 
address of the switch value descriptor table is not present 
in the associated switch descriptor table, the switch is 
invalid, and the error sequence described in step 1 would 
occur. 


You specify the address of the switch value descriptor table 
as the vtab parameter in the CSISSW macro call. 


The CSIS$SW macro call has the following format: 
Format 

label: CSISSW sw,mk,mkw,csflg,nflg,vtab,compflg 
Parameters 


label 


An optional symbol that names the resulting switch descriptor 
table entry and defines its address. To establish the address of 
a switch descriptor table, the first CSISSW macro call issued in 
the program must include a label. This label allows the table to 
be referenced by other instructions in the program. 


Sw 


The switch name to be stored as an entry in the switch descriptor 
table. This name may comprise any number of alphabetic 
characters. CSI compares the name entered on the command line 
with this switch name as entered in the switch descriptor table. 
This is a required parameter; if you omit it, the Assembler 
generates an .ERROR directive during assembly that causes the 
error message MISSING SWITCH NAME to be printed in the assembly 
listing. 


mk 


A mask that you define for the switch specified through the sw 
parameter. To enable CSI to indicate the presence of a given 
switch in a file specification, you must define a mask value for 
the switch, as follows: 


ASMSK = 1 
NUMSK = 2 
VWMSK = 40000 
XYMSK = 100000 


where the octal value that you assign to each symbol defines a 
unique bit configuration. This configuration is to be set in CSI 
mask word 1 (C.MKW1) of the control block when a defined switch 
is encountered ina file specification. 


mkw 
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When you specify the appropriate symbol as the mk parameter in 
the CSIS$SW macro call, the corresponding mask value is stored in 
the resulting switch descriptor table entry. Thus, a mechanism 
is established through which you can determine the particular 
combination of switches present in a file specification. For 
every matching entry found in the switch descriptor table, the 
corresponding bits are set in C.MKWl. 


The address in your program storage of a mask word that CSI 
changes each time it changes C.MKW1l. CSI stores the same value 
into this mask word that it stores into C.MKWl. This mask word 
can be manipulated, that is, changed or tested by the SET and 
CLEAR functions or by instructions in your program. You set the 
SET and CLEAR functions using the csflg parameter. 


Such an optional word may be reserved through a_ statement 
logically equivalent to the following: 


MASKX: .WORD 0 


csflg 


nflg 


vtab 


A symbolic argument that specifies the clear/set flag for a given 
switch. This parameter is optional; if you do not specify it, 
SET is assumed. You may specify either one of two symbolic 
arguments for this parameter, as follows: 


CLEAR - Indicates that the bits in the optional mask word 
corresponding to the switch mask are to be cleared, provided 
that you did not negate the switch. (If you negate the 
switch, the bits are set.) 


SET - Indicates, conversely, that the bits in the optional 
mask word in your task corresponding to the switch mask are to 
be set, provided that you did not negate the switch. (If you 
negate the switch, the bits are cleared.) 


If you specify other than SET or CLEAR, the Assembler generates 
an .ERROR directive that causes the error message INVALID 
SET/CLEAR SPEC to be printed in the assembly listing. 


Specifies an optional negation flag for the switch. If you 
specify this parameter, it indicates that the switch can be 
negated, for example, /-LI or /NOLI. 


If you specify this parameter as other than NEG, the Assembler 
generates an .ERROR directive that causes the error message 
INVALID NEGATE SPEC to be printed in the assembly listing. If 
you do not specify this parameter, the assumption is that switch 
negation is not allowed. 


The address of the switch value descriptor table associated with 
this switch. If you specify this optional parameter, it allows 
CSI to decode any switch values accompanying the switch, provided 
that you have defined an associated switch descriptor table entry 
for that switch. The CSISSV macro defines the switch value 
descriptor table. (If you specify the vtab parameter in the 
CSISSV macro, you need not specify it in the CSISSW macro call.) 
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compflg 


Defines the method CSI uses to compare the switch name entered on 
the command line with the value entered in the switch descriptor 
table by the sw parameter. Either LONG or EXACT may be 
specified. The default value is entered if you do not specify a 
value. 


Default - If you do not code the parameter, only the first two 
characters of the switch name (specified by sw) are entered into 
the switch descriptor table and only these two characters are 
compared when the command line is parsed. Additional characters 
in the command line switch name are ignored. 


LONG - All characters specified by the sw parameter are entered 
in the switch descriptor table. During compare processing, the 
first characters of the switch name on the command line must 
exactly match the value for the switch in the switch descriptor 
table. Additional characters in the command line switch name are 
ignored. 


EXACT - All characters specified by the sw parameter are entered 
in the switch descriptor table. During compare processing, all 
the characters of the switch name on the command line must 
exactly match the value in the switch descriptor table. Extra 
characters in either the command line or the table are treated as 
an error. 


The switch table must be aligned on an even address. The format of 
the switch descriptor table entry created by the CSISSW macro is shown 
in Figure 6-2. 


The switch name characters precede the control information in the 
table. The sign bit of each word indicates whether the following word 
contains more switch name characters. A sign bit set to 1 indicates 
that the next word contains more switch name characters, whereas a 
sign bit set to 0 indicates that this is the last word containing 
switch name characters. 


If the number of characters in the switch name is odd, the high-order 
byte of the last word contains zeros, and CSI ignores it. 


The sign bit of the first byte of the last word of the switch name is 
the EXACT match bit. If this bit is set to 1, additional characters 
in the switch name on the command line are treated as an error by CSI; 
if this bit is set to 0, additional characters are ignored. 


The switch name characters are followed by entry control information 
consisting of the CSI mask word, the address of the area task of a 
mask word corresponding to the CSI mask word, and the address of the 
switch value table. 


A bit setting of 1 in the low-order bit of the address of your mask 
word indicates the CLEAR function; a bit setting of 0 indicates the 
SET function. 


The last word of the switch descriptor table entry contains’ the 
address of the switch value table. A bit setting of 1 in the 
low-order bit of this word indicates that the switch may be negated. 
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Mask Word for this Switch 
Address of Optional User Mask Word 


Address of Switch Descriptor Table 
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Figure 6-2 Format of Switch Descriptor Table Entry 


The following example shows a 2-entry switch descriptor table created 
through successive CSISSW macro calls: 


ASSWT: CSISSW AS,ASMSK,MASKX,SET,,ASVTBL 
CSISSW NU,NUMSK,MASKX,CLEAR,NEG, NUVTBL 
CSISND ;END OF SWITCH DESCRIPTOR TABLE. 


The first parameter in the first statement creates an entry in the 
Switch descriptor table for the switch /AS. The second parameter is 
an equated symbol that defines the switch mask, and the third 
parameter (MASKX) is the address of an optional mask word in your task 
(see the description of the mkw parameter). The fourth parameter 
indicates that the bits in MASKX that correspond to the switch mask 
are to be set. The fifth parameter (the negation flag) is null. The 
last parameter is the address of the associated switch value 
descriptor table. 


The second statement creates a switch descriptor table entry for the 
switch /NU. In contrast to the first statement, the fourth parameter 
(CLEAR) indicates that the bits in the optional mask word (MASKX) in 
your task that correspond to the switch mask are to be cleared. The 
fifth parameter (NEG) allows the switch to be negated, and the last 
parameter is the address of the switch value descriptor table 
associated with this switch. 


Note that the switch descriptor table entry macros are terminated with 
the CSISND macro (see Section 6.2.4.3). 


6.2.4.2 CSISSV - Create Switch Value Descriptor Table Entry Macro - 
CSISSV defines a switch value descriptor table entry. For every 
switch value that you expect your task to find with a given switch in 
a file specification, a corresponding switch value descriptor table 
entry must be defined in your program so that the switch value can be 
decoded. This macro creates a 2-word entry in the switch value 
descriptor table. The format of this table is shown in Figure 6-3. 


The CSISSV macro call has the following format: 
Format 


CSISSV type,adr,len 
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Parameters 
type 
A parameter that specifies the conversion type for the switch 


value. Any one of four symbolic values may be specified. The 
possible conversion types include the following: 


ASCII - Indicates that the switch value is to be treated as an 
ASCII string. If you quote the string, the quotes are 
returned in the buffer as part of the string. If a quote 


appears anywhere in the switch value, all characters following 
it, up to the end of the line or another quote, are _ included 
in the string. 


NUMERIC - Indicates a numeric switch value is to be converted 
to binary using octal as a default conversion radix. 


OCTAL - Indicates a numeric switch value is to be converted to 
binary using octal as a default conversion radix. 


DECIMAL - Indicates a numeric switch value is to be converted 
to binary using decimal as a default conversion radix. 


If any parameter is specified other than these, an  .ERROR 
directive is generated during assembly that causes the error 
message INVALID CONVERSION TYPE to be printed in the assembly 
listing. If you do not specify any of the previously described 
parameters, ASCII is assumed by default. 


adr 
The address of your program location that is to receive the 
resultant switch value at the conclusion of switch processing. 
This parameter is required; if not specified, an .ERROR directive 
is generated during assembly that causes the error message VALUE 
ADDRESS MISSING to be printed in the assembly listing. 

len 


A numeric value that defines the length (in bytes) of the area 
that is to receive the switch value that results from switch 
processing. This parameter is also required; if not specified, 
an .ERROR directive is generated during assembly that causes the 
error message LENGTH MISSING to be printed in the assembly 
listing. 


The format of a switch value descriptor table entry created by a 
CSISSV macro is shown in Figure 6-3. 


The low-order byte of the first word in the switch value descriptor 
table indicates whether the conversion type is ASCII or numeric. The 
low-order byte of this word is set to 1 if ASCII is specified; it is 
set to 2 if NUMERIC or OCTAL is specified, and is set to 3 if DECIMAL 
is specified. The high-order byte of this word indicates the maximum 
allowable length (in bytes) of the switch value. 


If the conversion type is ASCII, the len parameter reflects’ the 
maximum nmumber of ASCII characters that can be deposited in the area 
defined through the adr parameter. The high-order byte of the first 
word in the switch value table then reflects the maximum length of the 
ASCII string. If the number of characters in the switch value exceeds 
the specified length, the extra characters are ignored. If, however, 
the actual number of ASCII characters present in the switch value 
falls short of the specified length, the remaining portion of the area 
receiving the resultant value is padded with nulls. 
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If the conversion type is numeric, the length of the resulting binary 
value is either two bytes or four bytes. If the size field is less 
than 4, 2 bytes are stored. If the size field is greater than 4, 4 
bytes are stored. You must align the buffer on a word boundary. 


If you specify the default conversion type for a switch value on 
numeric conversions, you can override it with a pound sign (#) or a 
period (.). Preceding a numeric value by a pound sign (for example, 
#10) forces the conversion type to octal; a numeric value followed by 
a period (for example, 10.) forces the conversion type to decimal. 
Note also that you may precede a numeric switch value with a plus sign 
(+) or a minus sign (-). The plus sign is the default assumption. If 
you specify an explicit octal switch value by using the pound sign 
(#), the arithmetic sign indicator (+ or -), if included, must precede 
the pound sign (for example, -#10). 


If the conversion type is decimal, the switch value is evaluated as a 
single number; an overflow into the high-order bit (bit 15) causes an 
error condition. However, if the conversion type is octal, a full 
16-bit value may be specified. 
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Figure 6-3 Format of Switch Value Descriptor Table Entry 


Examples of how the CSISSV macro call may appear in a program follow: 
ASVTBL: CSISSV ASCII,ASVAL,3 
CSISSV ASCII,ASVAL+4,3 
CSISND 7END OF SWITCH VALUE TABLE 
NUVTBL: CSISSV OCTAL,NUVAL, 2 
CSISSV DECIMAL, NUVAL+2, 2 
CSISND 7;END OF SWITCH VALUE TABLE 
In these examples, the first parameter in the CSIS$SV macro defines the 
conversion type. The next two parameters, in all cases, define the 
address and the length of the program location that is to receive the 


resultant switch value. 


You may reserve the required storage for the first switch value table 
ASVTBL: as follows: 


ASVAL: .BLKW 4 ;ASCII VALUE STORAGE 


You can similarly reserve the required storage for the second switch 
value table NUVAL: through the following statement: 


NUVAL: .BLKW 2 ;NUMERIC VALUE STORAGE 


Note again that switch value tables are terminated with the CSISND 
macro call. 
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6.2.4.3 CSISND - Define End of Descriptor Table - CSISND terminates 
descriptor tables with a l-word entry. Switch descriptor tables and 
switch value descriptor tables must be terminated with a  1l-word 
end-of-table entry. You can create this word, which contains 0, with 
the CSISND macro call. 


This macro call takes no arguments. The examples near the ends of 
Sections 6.2.4.1 and 6.2.4.2 illustrate the use of this macro call. 


CHAPTER 7 


THE TABLE-DRIVEN PARSER (TPARS) 


This chapter describes the table-driven parser (TPARS), which parses 
command lines. TPARS permits you to define and parse command lines in 
a unique syntax using TPARS-supplied macros, built-in variables, and 
your own code. 


TPARS parses command lines according to syntax and semantics or 
meaning. The command line is made up of syntax elements. TPARS 
evaluates each syntax element of the command line based on a 
predefined arrangement of those elements. MTPARS parses command lines 
using a table that you define. You can build a state table, which 
contains states and transitions, using the TPARS STATES and TRANS 
macros. A state delimits and represents a single syntax element on a 
command line. A transition is a statement that defines the processing 
required for parsing a given syntax element and contains instructions 
for further parsing at another state. TPARS uses subexpressions to 
resolve complex syntax elements. On the semantic level, TPARS also 
resolves the semantics or meaning of each element based on definitions 
supplied within action routines of your program. These action 
routines use TPARS macros, built-in variables, and your code to permit 
you to define and parse command lines. 


The parser routine that you write is included in your programs’ that 
parse command lines. TPARS is invoked from within an executing 
program by means of a CALL instruction. The CALL invokes the parser 
routine as well as the TPARS processor. For further information on 
the interrelationships among the calling program, the user-defined 
parser routine, and the TPARS processor, refer to Section 7.5. 


7.1 CODING TPARS SOURCE PROGRAMS 


This section describes the three TPARS macros required to initialize 
and define the state table. Also included in this section is 
information describing action routines, TPARS built-in variables, and 
TPARS subexpressions. 


7.1.1 TPARS Macros: ISTAT$, STATES, and TRANS 


TPARS provides macros that allow you to write a state table for 
parsing a unique command line. The ISTATS macro initializes a state 
table, the STATES macro defines a-state (a particular syntax element) 
in your state table, and the TRANS macro defines the conditions for 
transition to another state. 
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7.1.1.1 ISTATS Macro - Initialize the State Table - ISTATS 
initializes the state table. The state table is built using two 
macros, STATES and TRANS, which are described in Sections 7.1.1.2 and 
7.1.1.3, respectively. This state table is built into a program 
section. Keyword strings that you define for parsing command lines 
are also accumulated in a program section. A third program section is 
also provided for a keyword pointer table used to enter the list of 
keyword strings. The ISTATS macro initializes these program sections. 


A blank STATES macro must follow the TPARS state table. 
Format 
ISTATS statetable,keytable,SDEBUG 
Parameters 
statetable 


The label that you assign to the state table. TPARS recognizes 
this label as the start of the state table. 


keytable 


The label that you assign to the keyword table. MTPARS recognizes 
this label as the start of the keyword table. 


SDEBUG 


Directs the Assembler to list addresses of the state transition 
table in the assembly listing. These addresses are useful for 
tracing TPARS operation using a debug routine that you. supply 
(see Section 7.1.3.4). When you do not include SDEBUG, state 
transition table addresses are not listed. 


The state table is built in a program section named SSTATE, the 
keyword strings are accumulated in a program section named S$KSTR, and 
the keyword pointer table is built in a program section named SKTAB. 


If you define the symbol SRONLY, each of these program sections is 
generated as read-only. You generate ae read-only state table by 
specifying the symbol SRONLY before the ISTATS macro in the form: 


SRONLY = 1 
ISTATS statetable,keytable,SDEBUG 


STATES 


7.1.1.2 STATES Macro - Defining a Syntax Element - STATES declares 
the beginning of a state. This macro delimits one command line syntax 
element from another. A blank STATES macro must follow the TPARS 
state table. 
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Format 
STATES [label] 
Parameter 
label 
An alphanumeric symbol that defines the address of the state. 
Each state defined by a STATES macro consists of any number of 


transitions defined by TRANS macros. The TRANS macros parse each 
syntax element. 


7.1.1.3 TRANS Macro - Defining a Transition - The TRANS macro allows 
you to match each syntax element in a command line to a given type, 
supply a symbolic address to the next TRANS macro, supply an address 
of an action routine that may be required to further process the 
syntax element, and supply a mask that you may use as a flag in the 
parsing process. 


Format 


TRANS type[,label] [,action] [,mask] [,maskaddr] 
[, SEXIT] 


Parameters 
type 
The type of command line syntax element being parsed. You code 


the type parameter using one of the following types of command 
line elements: 


Element Type Description 
SANY Matches any single character. 
SALPHA Matches any single alphabetic character (A-Z). 
S$DIGIT Matches any single digit (0-9). 
SLAMDA Matches an empty. string. This transition is 


always’ successful. LAMDA transitions are useful 
for getting action routines called without passing 
any of the input string. 


SNUMBR Matches any number. A number consists of a string 
of digits; a concluding period is optional. 
Numbers not followed by a period are interpreted 
as octal. Numbers followed by a period are 
interpreted as decimal and the decimal point is 
included in the matching string. A number is 
terminated by any Ononnumeric character. Values 
through 2**32-1 are converted to 32-bit unsigned 
integers. 


SDNUMB Matches a decimal number. The string of digits is 
interpreted as decimal. With the exception that 
the matched string does not include the trailing 
decimal point, TPARS treats SDNUMB the same way it 
treats SNUMBR. 
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Element Type Description 


SSTRNG Matches any alphanumeric character string. The 
string will not be null. 


$RAD50 Matches any legal Radix-50 string, that is, any 
string containing alphanumeric characters, or the 
period (.), or dollar sign (S$) characters. If you 
require Radix-50 conversion, the action routine in 
your code must convert this number. 


SBLANK Matches a string of blank and/or tab characters. 


$EOS Indicates the position of the end of an input 
string. Once TPARS has’7~ reached the end of the 
input string, SEOS is the equivalent of that 
position as many times as SEOS is encountered in 
the state table. 


char Matches a single character in the syntax element 
whose ASCII code corresponds to the value of char. 
The value of char must be a 7-bit ASCII code; that 
is, the value must be in the range 0-177 (octal). 
Specify a single quote (') before char, such as 'A 
or 'X. 


"keyword" Matches a specified keyword. Keywords can be any 
length, can contain only alphanumeric characters, 
must be in uppercase, and are terminated by the 
first nonalphanumeric character encountered in 
parsing the keyword. The maximum number of 
keywords allowed in a state table is 64. 


!label Matches the string processed by passing control to 
and executing the state table section that starts 
with a STATES macro that has the label parameter 
specified here as !label. In effect, this type 
parameter passes control to a STATES macro 
subroutine or subexpression. For information on 
TPARS subexpressions, see Section 7.1.4. 


[label] 
[SEXIT] 


The label associated with a STATES macro to which execution 
control will pass after the code for this TRANS transition is 
executed. If the label parameter is omitted, execution control 
passes on to the next sequential STATES macro. A null label 
parameter is allowed only for the last transition in a state; a 
TRANS macro with a null label field must follow a TRANS macro. 


Specifying SEXIT in the label field terminates *TPARS execution 
and returns control to the calling program. SEXIT also 
terminates a TPARS subexpression. 


action 
The label of an action routine that you include in the parser 


routine of your code. This routine can include TPARS built-in 
variables, described in Section 7.1.3 below. 
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mask 
A maskword to be stored in a location pointed to by the maskword 
address whenever the TRANS macro is executed. If you specify 
mask, you must specify the maskaddr parameter as well (see _ the 
following parameter). This maskword is ORed into maskaddr 
(described below) when the transition is taken (after the action 
routine is called). 

maskaddr 


The label for an address into which TPARS stores the value 
specified by the mask parameter. You must specify the maskaddr 
parameter if you specify mask. 


The mask and maskaddr parameters provide a convenient means for 
flagging the execution of a particular transition. 


7.1.2 Action Routines and Built-In Variables 


Action routines process command line elements at the semantic level. 
That is, a given syntax element can have more than one meaning. 
Action routines determine and validate the meaning of the syntax 
elements. 


You write action routines in your parsing program to perform unique 
functions related to your program's requirements. 


7.1.2.1 TPARS Built-In Variables - TPARS provides’ the following 
built-in variables for action routines: 


- PSTCN Returns the character count of the portion of the 
input string matched by this transition. This 
character count is valid for all syntax types 
recognized by TPARS, including subexpressions. 


-PSTPT Returns the address of the portion of the input 
string matched by this transition. This address 
is valid for all syntactical types recognized by 
TPARS, including subexpressions. 


- PNUMH Returns the high-order binary value of the number 
returned by a SNUMBR or SDNUMB- syntax type 
specification. 


- PNUMB Returns the low-order binary value of the number 
returned by a SNUMBR or SDNUMB- syntax type 
specification. 

- PCHAR Returns the character found by the SANY, SALPHA, 


SDIGIT, or char syntax type specifications. 


- PFLAG Returns the value of the flag word passed to TPARS 
by register 1 (Rl). Action routines can modify 
this word to change options dynamically. 


- TPDEB Contains the entry address of the optional debug 
routine that you write. 
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R3 Returns the byte count of the remainder of the 
input string. When the action routine is called, 
the string does not include the characters matched 
by the current transition. 


R4 Returns the address of the remainder of the input 
string. When the action routine is called, the 
string does not include the characters matched by 
the current transition. 


7.1.2.2 Calling Action Routines - Action routines are called by a JSR 
PC instruction. Action routines may modify registers RO, Rl, and R2; 
all other registers must be preserved. 


7.1.2.3 Using Action Routines to Reject a Transition - Action 
routines can reject a transition by returning to CALL+4 rather than to 
CALL+2. That is, the action routine performs the same function as an 
ADD #2,(SP) before returning to the caller. This technique allows 
additional processing of syntax types and extending the syntax types 
beyond the set provided by TPARS. 


When an action routine rejects a transition, that transition has no 
effect. TPARS continues to attempt to match the remaining transitions 
in the state. 


7.1.2.4 Optional Debug Routine for RSX-l1l Users - A debug routine 
that you supply can be called by MTPARS at each state transition 
allowing TPARS operation to be traced. For example, the routine can 
be written to display the contents of R5 each time the routine is 
called; R5 contains the current transition table address. By 
comparing the addresses displayed with the TPARS assembly listing 
showing the state transition table addresses, TPARS operation can be 
monitored. 


If a debug routine that you supply is to be called by TPARS, your task 
must first specify the entry point address for the debug routine in 
TPARS location .TPDEB, as follows: 

MOV #DENTER,.TPDEB 


Then, invoke TPARS with the .TPARD entry point (rather than with 
-TPARS). MTPARS is invoked as described in Section 7.4. 


Upon entry to the debug program, CPU registers contain the following: 
R3 = Length of remainder of input string 


R4 


Address of remainder of input string 
RS5 = Current address of transition table 


The debug routine must save and restore all registers prior to 
returning to TPARS. 


For addresses displayed by the debug routine to be useful, you must 
obtain an assembly listing showing the addresses of the state 
transition tables. These addresses are listed by the assembler if the 
optional SDEBUG parameter is provided in the ISTATS macro call (see 
Section 7.1.1.1). 
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7.1.3 TPARS Subexpressions 


A TPARS subexpression is a series of states and transitions analogous 
to a subroutine. In general, such a series of states and transitions 
is used more than once during the parsing process. 


Subexpressions begin with a STATES macro specifying the label of the 
subexpression. You follow this macro by the states and transitions 
that comprise the body of the subexpression. To terminate the 
subexpression, specify a TRANS macro with the SEXIT keyword specified 
in the label field. The general form of a subexpression is shown in 
the example below. 


In this example, control is directed to the subexpression by a TRANS 
macro that specifies a !label syntax element as the type parameter: 


TRANS !UIC,NEXT 
TPARS then directs control to the STATES macro with the label UIC: 


STATES UIC 
TRANS '[ 


STATES 
TRANS SNUMBR,,SETGN 


STATES 
TRANS <',> 


STATES 
TRANS SNUMBR,,SETPN 


STATES 
TRANS '],SEXIT 


When the UIC subexpression completes processing, control passes to the 
state labeled NEXT. 


7.2 GENERAL CODING CONSIDERATIONS 


This section contains information on how to arrange syntax types in a 
state table and how to direct TPARS to ignore blanks and table 
characters in a command line, and rules for entering special 
characters (commas and angle brackets). 


7.2.1 Suggested Arrangement of Syntax Types in a State Table 


The transitions in a state may represent several syntax types; a 
portion of a string being scanned often matches more than one syntax 
type. Therefore, the order in which you enter the types in the state 
table is critical. Transitions are always scanned in the order in 
which they are entered, and the first transition matching a_ string 
being scanned is the transition taken. Therefore, the following order 
is recommended for states containing more than one syntax type: 


char 
keyword 
$EOS 
SALPHA 
SDIGIT 
SBLANK 
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SNUMBR 
SDNUMB 
SSTRNG 
SRAD50 
SANY 

SLAMDA 


Placement of !label transitions in a state depends on the types and 
positions of other syntax types in the state, as well as on the syntax 
types in the starting state of the subexpression. 


7.2.2 Ignoring Blanks and Tabs in a Command Line 


Bit zero of the low byte of Register 1 (Rl) controls processing of 
blanks and tab characters. If this bit is 1 when TPARS is invoked, 
blanks and tab characters are processed in the same way any other 
ASCII character is processed; they are treated as syntax elements that 
require validation by TPARS. If this bit is set to 0, blanks and tab 
characters are interpreted as terminator characters; they are ignored 
as syntax elements. In neither case does TPARS modify the command 
line. 


When blanks are being ignored, the S$BLANK syntax type never matches an 
element on the command line. Also, when this option is in effect, 
values returned to the !label syntax type by .PSTCN or .PSTPT may 
contain blanks or tabs, even though none were requested. The examples 
below show how TPARS parses the string: 


ABC DEF 
with and without the blank-suppress option. 


In the first example, an extra state is required to parse the blank: 


STATES 
TRANS SSTRNG 
STATES 
TRANS SBLANK 
STATES 
TRANS SSTRNG 


When TPARS is directed to ignore blanks and tab characters, the same 
string can be parsed using only two states: 


STATES 
TRANS SSTRNG 
STATES 
TRANS SSTRNG 


7.2.3 Entering Special Characters 


In char syntax elements, MACRO-1l interprets commas (,), semicolons 
(;), and angle brackets (< >) as special characters. The comma is 
interpreted as an argument separator and angle brackets are used _ to 
parenthesize special characters. 
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To include a comma or a semicolon in a char syntax element string, use 
angle brackets: 


TRANS <',> 


Angle brackets cannot be passed as string elements in macro arguments. 
If required in a "char" expression, they must be expressed 
symbolically, for example: 


LA = ‘< 
TRANS LA 


7.2.4 Recognition of Keywords 


When TPARS encounters a transition table entry that specifies a 
keyword, it first scans from the current point in the input string in 
search of a delimiter (nonalphanumeric) character. The characters 
between the current input point and the next delimiter are then 
assumed to be a possible keyword and are matched against the entries 
in the keyword table. For this reason, the following example will not 
work as expected: 


STATES 
TRANS "NO" ,STATE1,SETNEG 
TRANS SLAMDA, ,SETPOS 


STATES STATE] 
TRANS "AA", 20% 
TRANS "BBO jes 


When TPARS encounters the keyword NO, it scans and attempts to match 
the string "NOAA" or "NOBB". If exact matching is requested, neither 
the "NO" transition nor the "AA" transition will match. In addition, 
if keyword matching is limited to two characters, the "NO" transition 
will match but TPARS will skip past "NOAA" so that the "AA" transition 
can be taken. You can use the following example to achieve the 
desired operation: 


STATES 
TRANS !NONO, STATE], SETNEG 
TRANS SLAMDA, ,SETPOS 


STATES STATE 
TRANS "AA", 
TRANS "BB" ,..- 


STATES NONO 
TRANS 'N 


STATES 
TRANS '0O,SEXIT 


In this example, TPARS attempts to match the subexpression NONO to the 
"NO" prefix one character at ae time. This bypasses the keyword 
scanning of TPARS, allowing the input pointer to be left pointing at 
"AA" or "BB". If NONO fails, the input pointer will not be changed 
and the scan can continue by looking for "AA" or "BB". 
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7.3 PROGRAM SECTIONS GENERATED BY TPARS MACROS 


TPARS macros generate three program sections. Data for the STATES 
macro are stored in the program section SSTATE, whereas data for the 
TRANS macro are stored in program sections SKSTR and SKTAB. SKTAB 
contains addresses for each of the entries of the keyword syntax type. 
SKSTR contains the keyword entries separated by character code 377 


(octal). 


Each state consists of its transition entries concatenated in the 
order in which you specify them. The state label, if specified, is 
equated to the address of the first transition in the. state. Each 
transition consists of from one to six words, as follows: 


ee 
Type Extension 
Action Return Address 
Maskword Address 
Target State Label 


Z2K-314-81 


The type byte of the first word may contain the following values: 


SLAMDA = 300 

SNUMBR = 302 

SSTRNG = 304 

SBLANK = 306 

SSUBXP = 310 Used in the !label type. 
SEOS = 312 

SDNUMB = 314 

SRAD50 = 316 

SANY = 320 

SALPHA = 322 

SDIGIT = 324 

char = ASCII code for the specified character 
keyword = 200+n (See explanation below.) 


The value of keyword is 200+n, where n is an index into the keyword 
table. The keyword table is an array of pointers to keyword strings, 
which are stored in the program section S$KSTR. Keyword strings in 
SKSTR are separated from each other by 377 (octal). 


Bits in the flags byte indicate whether parameters for the TRANS macro 
are specified: 


Bit Meaning 


Type extension is specified. 

Action routine label is specified. 

Target state label is specified. 

Maskword is specified. 

Maskword address is specified. 

Indicates last transition in the current state. 


SP WN FO 
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7.4 INVOKING TPARS 


You control execution of TPARS using the calling conventions and 
options described in this section. You invoke TPARS from within an 
executing program by the instruction 


CALL - TPARS 


When a debug routine that you specify traces a TPARS operation (see 
Section 7.1.3.4), a special entry point is called, as follows: 


CALL - TPARD 
When your task calls TPARS in this manner, TPARS calls the debug 
routine at each state transition. If your task invokes TPARS by the 


-TPARS entry point, the debug routine entry point address in .TPDEB is 
cleared and the debug routine is not called. 


7.4.1 Register Usage and Calling Conventions 


When TPARS is invoked, registers in the calling program must contain 
the following information: 


Rl = Options word 

R2 = Pointer to the keyword table 

R3 = Length of the string to be parsed 

R4 = Address of the string to be parsed 

R5 = Label of the starting state in the state table 


On return from TPARS processing, registers contain the following 
information: 


R3 
R4 


Length of the unscanned portion of the string 
Address of the unscanned portion of the string 


The values of all other registers are preserved. 


The Carry bit in the Processor Status Word returns 0 for a_ successful 
parse; the Carry bit is set when TPARS finds a syntax error. 


For an example of a calling sequence for TPARS, refer to Section 
7.6.1. 


7.4.2 Using the Options Word 


The low byte of the options word contains flag bits. The only flag 
bit defined is bit zero, which controls processing of blanks. If bit 
zero is set to 1, blanks are interpreted as syntax elements. If bit 
zero is set to 0, blanks are ignored as syntax elements. 


The high byte of the options word controls abbreviation of keywords. 
If the high byte is set to 0, keywords being parsed must exactly match 
their corresponding entries in the state table. If the high byte is 
set to a number, keywords being parsed may be abbreviated to that 
number of characters. Keywords in the string that are longer than the 
number specified must be spelled correctly up to the length specified 
by the number. 


TPARS clears the Carry bit in the Processor Status Word when it 
completes processing successfully. This occurs when a transition is 
made to SEXIT that is not within a subexpression. 
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If a syntax error occurs, TPARS sets the Carry bit in the Processor 
Status Word and terminates. 


A syntax error occurs when there are no syntax elements in the current 
state that match the portion of the string being scanned. Illegal 
type codes and errors in the state table can also cause ae syntax 
error. 


TPARS processing requires that the addresses in the state table and 
the keyword tables be reliable; bad addresses may cause program 
termination. 


The only syntax types that can match the end of the string are SEOS 
and S$LAMDA. 


7.5 HOW TO GENERATE A PARSER PROGRAM USING TPARS 


Three processing steps generate a parser program using TPARS, as shown 
in Figure 7-1. The source program must contain .MCALL statements for 
three macros: ISTATS, STATES, and TRANS. These three -MCALL 
statements must precede the statements that comprise the state table 
and action routines. 


Assembling the source module produces an object module composed of 
three program sections. The assembly listing showing the code 
produced by the state table macros is not straightforward. The binary 
output of the macros is delayed by one statement. Thus, if you enable 
the listing of macro-generated binary code during assembly of the 
code, the binary code appearing after a macro call is, in fact, the 
result of the preceding macro call. Error messages generated by macro 
calls are similarly delayed. This is the reason an additional STATES 
macro is required to terminate the state table. 


When the parser program is linked and is in task image form, it can be 
invoked from within your executing task, as shown in Figure 7-2. 
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PARSER.SRC 


MCALL ISTAT$ 


1. Write a source program that MCALL STATE$ 
EDI <«----- > includes the required MCALL a MCALL TRANS 
statements. STATES 


STATES 


PARSER.OBJ 
MACRO-11 


2. | Assemble the source program to aaa 
produce an object module. SKTAB 


PARSER.SRC 


PARSER.OBS 


MYFILE.TSK 
3. Execute the Task Builder to ase 
MYFILE.OBJ produce a task image including 
the parser. 
UPDATE.OBJ 
ZK-298-81 


Figure 7-1 Processing Steps Required to Generate a Parser 
Program Using TPARS 
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Figure 7-2 shows the CALL .TPARS statement that invokes the parser 
program and the TPARS processor. As the parser executes the state 
table, it calls action routines. These action routines access code in 
the TPARS processor to perform such functions as returning the values 
of the built-in variables. When the state table completes execution, 
TPARS receives control and passes control back to the calling program. 


Executing User-defined TPARS 
User Program Parser Program Processor 


STATE$ 


* 


* 


CALL .TPARS Action 
Routines 


ZK-299-81 


Figure 7-2 Flow of Control When TPARS Is Called from an Executing 
User Program 


7.6 PROGRAMMING EXAMPLES 


This section includes three programming examples of how TPARS can be 
used in your program. The first example shows the code required to 
parse a UFD command line for RSX-ll. The second example shows the use 
of subexpressions and how to reject transitions. The third example 
shows how to use subexpressions to parse complex command lines. 


7.6.1 Parsing a UFD Command Line 

This example shows the code required to parse a UFD command line. It 
includes a state table and action routines. The general form of the 
UFD command line is as follows: 


UFD DKO:LABEL [201,202] /ALLOC=100./PRO=[RWED, RWED, RWE,R] 


The action routines in this parser program return the _ following 
values: 


SUDEV Device name (2 ASCII characters) 

SUUNIT Unit number (binary) 

SUVNML Byte count of the volume label string 
SUVNAM Address of the volume label string 

SUUIC Binary UIC for which to create a directory 
SUALL Number of directory entries to preallocate 
SUPRO Binary protection word for UFD 

SFLAGS Flags word containing the following bits: 


UF.ALL Set if allocation was specified 
UF.PRO Set if protection was specified 
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The label and the /ALLOC and /PRO switches are optional. 
sequence for this routine is as follows: 


CLR R1 

MOV #UFDKTB,R2 
MOV COUNT,R3 
MOV ADDR,R4 
MOV #START,R5 
CALL - TPARS 

BCS ERROR 


The 


calling 


The following is an example of the parser routine that you write: 


=e 


-TITLE STATE TABLE FOR UFD COMMAND LINE 


-MCALL 


ISTATS 


; READ OVER COMMAND NAME 


READ DEVICE AND 


=e 


- GLOBL 


STATES 
TRANS 


ISTATS, STATES, TRANS 


TO BE USED WITH BLANK SUPPRESS OPTION 


UFDSTB, UFDKTB 


START 


START 
Ww UFD i 


UNIT NUMBER 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 
TRANS 


STATES 
TRANS 


; READ VOLUME LABEL 


; READ UIC 


STATES 
TRANS 
TRANS 


STATES 
TRANS 


SALPHA, ,SETDV1 


SALPHA, ,SETDV2 


SNUMBR, DEV1,SETUNT 
SLAMDA 


DEV1 


SSTRNG, RUIC,SETLAB 
SLAMDA 


RUIC 
!UIC 


; SCAN FOR OPTIONS AND END OF LINE 


STATES 
TRANS 
TRANS 


STATES 
TRANS 
TRANS 


OPTS 
SEOS, SEXIT 


re 


"ALLOC",ALC, ,UF.ALL, SFLAGS 
“PRO",PRO,,UF. PRO, SFLAGS 
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; SET ALLOCATION 


STATES ALC 
TRANS '= 


STATES 
TRANS SNUMBR,OPTS,SETALC 


; PROTECTION 


STATES PRO 
'= 


TRANS 

STATES 

TRANS "[L,,IGROUP 
STATES SPRO 

TRANS '] ,OPTS , ENDGRP 
TRANS <',>,SPRO,NXGRP 
TRANS 'R,SPRO,SETRP 
TRANS 'W,SPRO,SETWP 
TRANS 'E, SPRO, SETEP 
TRANS 'D, SPRO,SETDP 


; SUBEXPRESSION TO READ AND STORE UIC 


STATES UIC 
TRANS at 


STATES 
TRANS SNUMBR, ,SETGN 


STATES 
TRANS <",> 


STATES 
TRANS SNUMBR, ,SETPN 


STATES 
TRANS ') ,SEXIT 


STATES 
; STATE TABLE SIZE: 60 WORDS 
7 KEYWORD TABLE SIZE: 8 WORDS 
; KEYWORD POINTER SPACE: 3 WORDS 
-SBTTL ACTION ROUTINES FOR THE COMMAND LINE PARSER 
; DEVICE NAME CHAR 1 


SETDV1: :MOVB - PCHAR, SUDEV 
RETURN 


; DEVICE NAME CHAR 2 


SETDV2: :MOVB - PCHAR, SUDEV+1 
RETURN 


; UNIT NUMBER 
SETUNT: :MOV - PNUMB, SUUNIT 


RETURN 
; VOLUME LABEL 
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SETLAB: :MOV . PSTCN, SUVNML 
MOV .PSTPT, SUVNAM 
RETURN 

: PPN - GROUP NUMBER 

SETGN:: MOVB . PNUMB, SUUIC4+1 
BR TSTPPN 

> PPN - PROGRAMMER NUMBER 

SETPN:: MOVB .PNUMB, SUUIC 

TSTPPN: TST » PNUMH ; 
BNE 10$ 
TSTB . PNUMB+1 : 
BEQ 20$ 

10S: ADD #2, (SP) ; 

20S: RETURN 


; NUMBER OF ENTRIES TO ALLOCATE 


SETALC: :MOV - PNUMB, SUALL 


RETURN 


; SET PERMISSIONS 
; INITIALIZE 


IGROUP: :MOV #4,GRCNT 


; MOVE TO NEXT PERMISSIONS CATEGORY 


NXGRP: : SEC 
ROR 
ASR 
ASR 
ASR 
DEC 
BGE 

BADGRP: ADD 

308: RETURN 


; SET READ PERMIT 


SETRP:: BIC 
RETURN 


; SET WRITE PERMIT 


SETWP:: BIC 
RETURN 


; SET EXTEND PERMIT 


SETEP:: BIC 
RETURN 


; SET DELETE PERMIT 


SETDP:: BIC 
RETURN 


7 END OF PROTECTION SPEC 


CHECK FOR 0 HIGH ORDER 
CHECK FOR BYTE VALUE 


BAD VALUE - REJECT TRANSITION 


; FORCE ONES 
SUPRO 
SUPRO ; SHIFT TO NEXT GROUP 
SUPRO 
SUPRO 
GRCNT ; COUNT GROUPS 
308 ; TOO MANY IS AN ERROR 
#2, (SP) ; IF SO, REJECT TRANSITION 
#F P.RDV*10000, SUPRO 
#FP.WRV*10000, SUPRO 
#F P.EXT*10000, SUPRO 
#FP.DEL*10000,SUPRO 
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ENDGRP: : TST GRCNT ; CHECK THE GROUP COUNT 
BNE BADGRP ; MUST HAVE 4 
RETURN 
- END UFD 


7.6.2 Using Subexpressions and Rejecting Transitions 


The following example is an excerpt from a state table that parses a 
string in which the first character is interpreted as a quote 
character. This typical construction occurs in many editors. and 
programming languages. The action routines associated with the state 
table return the byte count and address of the string in the locations 
QSTC and QSTP. The quoting character is returned in location QCHAR. 


MAIN LEVEL STATE TABLE 


=e Te MO 


PICK UP THE QUOTE CHARACTER 


STATES STRING 
TRANS SANY, ,SETQ 


ACCEPT THE QUOTED STRING 


=e 


STATES 
TRANS !QSTRG, ,SETST 


GOBBLE UP THE TRAILING QUOTE CHARACTER 


=e 


STATES 
TRANS SANY,NEXT,RESET 


SUBEXPRESSION TO SCAN THE QUOTED STRING 
THE FIRST TRANSITION WILL MATCH UNTIL IT IS REJECTED 
BY THE ACTION ROUTINE 


we te MO 


STATES QSTRG 

TRANS SANY,QSTRG, TESTQ 
TRANS SLAMDA, SEXIT 
STATES 


ACTION ROUTINES 


me Me NE 


STORE THE QUOTING CHARACTER 


SETQ: MOVB - PCHAR, QCHAR 
INCB - PFLAG ; TURN OFF SPACE FLUSH 
RETURN 


; TEST FOR QUOTING CHARACTER IN THE STRING 


TESTQ: CMPB . PCHAR, QCHAR 
BNE 10$ 
ADD #2, (SP) ; REJECT TRANSITION ON MATCH 
10S: RETURN 


; STORE THE STRING DESCRIPTOR 


SETST: MOV -PSTPT,QSTP 
MOV - PSTCN, QSTC 
RETURN 


THE TABLE-DRIVEN PARSER (TPARS) 


; RESET THE SPACE FLUSH FLAG 


RESET: DECB . PFLAG 
RETURN 


7.6.3 Using Subexpressions to Parse Complex Command Lines 


The following excerpt from a state table shows how subexpressions are 
used to parse complex command lines. 


The state table accepts a number followed by a keyword qualifier. 
Depending on the keyword, the number is interpreted as either octal or 
decimal. The binary value of the number is returned in the tagged 
NUMBER. The following types of strings are accepted: 


10 /OCTAL 
359 /DECIMAL 
77777 /OCTAL 


; MAIN STATE TABLE ENTRY - ACCEPT THE EXPRESSION AND 
; STORE ITS VALUE 


STATES 
TRANS !ONUMB , NEXT ,SETNUM 
TRANS !DNUMB, NEXT,SETNUM 


; SUBEXPRESSION TO ACCEPT OCTAL NUMBER 


STATES ONUMB 
TRANS SNUMBR 


STATES 

TRANS '/ 

STATES 

TRANS "“OCTAL", SEXIT 


; SUBEXPRESSION TO ACCEPT DECIMAL NUMBER 


STATES DNUMB 
TRANS SDNUMB 


STATES 

TRANS ‘/ 

STATES 

TRANS "DECIMAL" ,SEXIT 
STATES 


; ACTION ROUTINE TO STORE THE NUMBER 


SETNUM: MOV - PNUMB, NUMBER 
MOV - PNUMH , NUMBER+2 
RETURN 


The contents of .PNUMB and .PNUMH remain undisturbed by all state 
transitions except the S$NUMBR and SDNUMB types. 


Because of the way in which subexpressions are processed, calls to 
action routines from within subexpressions must be handled with care. 
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When a subexpression is encountered in a transition, TPARS saves its 
current context and calls itself, using the label of the subexpression 
as the starting state. If the subexpression parses successfully and 
returns by means of SEXIT, the transition is taken and control passes 
to the next state. If the subexpression encounters a syntax error, 
TPARS restores the saved context and tries to take the next transition 
in the state. 


However, TPARS provides no means for resetting original values changed 
by action routines that were called by subexpressions. Therefore, 
action routines called from subexpressions should store results in an 
intermediate area. Data in this intermediate area can then be 
accessed by an action routine called from the primary level of the 
state table. 


CHAPTER 8 


SPOOLING 


FCS provides facilities at both the macro and subroutine level to 
queue files for subsequent printing; thus, your task can queue a print 
job. There are several ways for your task to spool output for 
printing but you cannot control the printing from within your task as 
you can with the PRINT command. You can, however, use the DCL SET 
QUEUE command to alter the attributes of the print job once the job 
appears in the queue. 


8.1 PRINTS MACRO 
A task issues the PRINT$ macro to queve a file for printing on a 
specified device. The specified device must be a unit record, 
carriage-controlled device such as a line printer or terminal. The 
file is placed in the default queue PRINT. If the device is not 
specified, LP: is used. 
The file to be spooled must be open when the PRINTS macro is’ issued. 
Once the file is queued, PRINTS closes the file. Error returns differ 
from normal FCS conventions, and are described in Section 8.3. 
The PRINTS macro call has the following format: 
Format 

PRINTS fdb,err,,dev,unit,pri,forms,copies,presrv 
Parameters 


fdb 


The address of the associated FDB. This parameter need not _ be 
present if the address of the associated FDB is already in RO. 


err 


The address of an optional, error-handling routine that you code. 
See Section 8.3. 


The following parameters are not applicable to RSX-11M/M-PLUS'= and 
Micro/RSX: dev, unit, pri, forms, copies, presrv 


8.2 .PRINT SUBROUTINE 


Your task can open a file on disk, send output to the disk, and close 
the file either by using the PRINTS macro call or by calling the 
»-PRINT subroutine to spool the output. The .PRINT subroutine is 
called to queue a file for printing. RO must contain the address of 
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the associated FDB. The file must be open when .PRINT is called. The 
file is placed in the default queue PRINT and then the .PRINT routine 
closes the file. One copy of the file is printed on the LP: device. 
In your task, it may be preferable to call the .PRINT subroutine if 
the routine resides in FCSRES. Using the PRINTS macro causes all the 
code of .PRINT to appear in your task each time it is used. 


Section 8.3 describes error handling for the .PRINT file control 
routine. 


8.2.1 Opening a File on Disk and Using the PRINT Command 


As stated in the opening of this section, your task can open a file on 
disk, send output to that disk, and close the file. When the task 
exits, the PRINT command can print the file. This is the only method 
that gives you access to the PRINT command qualifier. Other than 
using the qualifier, your task can use PRINTS or .PRINT; you then wait 
until the job is in the queve and alter its attributes with the SET 
QUEUE command. 


If you run your task from an indirect command file or batch job that 
includes a PRINT command after the task exits, the difference between 
spooling from within a task or from outside it is negligible. 


You can use the SPWNS directive in the task to issue the PRINT 
command. (Refer to the RSX-1LIM/M-PLUS and Micro/RSX Executive 
Reference Manual.) 


8.2.2 Opening a File on LP: 


Your task can use the OPENS macro to name the output device. FCS 
opens the file on pseudo device SP0O:. The file is placed in the 
device-specific queue for the device you named. When your task has 
finished writing to this file, close it with a CLOSES macro. The file 
is deleted after it is printed. This file does not remain in any 
directory but is identified by a file-ID number labeled FID in the 
SHOW QUEUE display. 


8.3 ERROR HANDLING 


The error returns provided with PRINTS and .PRINT differ from the 
Standard FCS error returns. Unlike FCS error returns, PRINTS and 
»-PRINT error codes are placed in F.ERR or in the directive status 
word, depending on when the failure occurred. 


If the failure is FCS related (for example, the PRINTS macro cannot 
close the file), the Carry bit is set and F.ERR contains the error 
code. If the failure is related to the SEND/REQUEST directive that 
queves the file, the Carry bit is set and the directive status word 
contains an error code. Directive status word error codes are listed 
in the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual. 
Normally, once you determine that the C-bit is set, any error routine 
that you code should first test F.ERR and then test the directive 
Status word error code. 


APPENDIX A 


FILE DESCRIPTOR BLOCK 


A File Descriptor Block (FDB) contains file information that is used 
by File Control Services (FCS) and the file control primitives. The 
layout of an FDB is illustrated in Figure A-l. Table A-l defines the 
offset locations within the FDB. 


The offset names in the File Descriptor Block may be defined either 
locally or globally, as shown below: 


FDOFSL 7;DEFINE OFFSETS LOCALLY. 

FDOFF$ DEFSL ;DEFINE OFFSETS LOCALLY. 

FDOFF$ DEFSG ;DEFINE OFFSETS GLOBALLY. 
NOTE 


When you refer to FDB locations, it is essential 
to use the symbolic offset names, rather than the 
actual address of such locations. The position 
of information within the FDB may be subject to 
change from release to release, whereas’ the 
offset names remain constant. 


F.RATT 


F.RCTL 


FILE DESCRIPTOR BLOCK 


File Attribute Section 


Record attributes Record type 


Highest virtual block number allocated 


1 


End of file block number 


Record- or Block-Access Section 


First free byte in last block 


Block I/O buffer descriptor 


meee i ee ee 


17 


User’s record buffer descriptor 


Next record buffer descriptor 


Record number for random records 


Size in blocks of contiguous file 
Address to read in statistics block 


Figure A-~l File Descriptor Block Format 


0 F.RTYP 
2 F.RSIZ 
4 F.HIBK 


10 F.EFBK 


14 F.FFBY 


16 F.RACC 
20 F.BKDS 


20 F.URBD 


24 F.NRBD 


24 F.BKST 
26 F.BKDN 


30 F.OVBS 
30 F.NREC 


32 F.EOBB 
34 F.RONM 


34 F.CNTG 
36 F.STBK 
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File-Open Section 


a ee 


Biock-Buffer Section 


F.BKP1 51 QIO event flag 50 F.EEN or F.BKEF 
62 F.BBFS 


Block I/O virtual block number 64 F.BKVB 


40 F.ALOC 


F.FACC 43 42 F.LUN 


44 F.DSPT 
46 F.DFNB 


Virtual block number 64 F.VBN 
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Figure A-1l (Cont.) File Descriptor Block Format 


Table A-1 
FDB Offset Definitions 


Symbolic Size Contents 

Offset (in bytes) 

Name 

F.RTYP i Record-type byte. This byte is set, as 
follows, to indicate the type of records for 
the file: 


F.RTYP = 1 to indicate fixed-length 
records (R.FIX). 

F.RTYP = 2 to indicate variable-length 
records (R.VAR). 

F.RTYP = 3 to indicate sequenced records 
(R.SEQ). 

F.RTYP = 4 to indicate stream ASCII 
records (R.STM). 
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Table A-1l (Cont.) 
FDB Offset Definitions 


Symbolic Size Contents 

Offset (in bytes) 

Name 

F.RATT 1 Record attribute byte. Bits 0 through 3 are 
set to indicate record attributes, as 
follows: 


Bit 0 = 1 to indicate that the first byte 
of a record is to contain a FORTRAN 
carriage control character (FD.FTN) ; 
otherwise, it is 0. 


Bit 1 = 1 to indicate for a carriage 
control device that a line feed is to be 
performed before the line is printed and 
a carriage return is to be performed 
after the line is printed (FD.CR); 
otherwise, it is 0. 


Bit 2 = 1to indicate the "print file 
format" (FD.PRN). FCS allows this 
attribute but does not interpret the 
format word. 


Bit 3 = 1 to indicate that records cannot 
cross block boundaries (FD.BLK); 
otherwise, it is 0. 


F.RSIZ 2 Record-size word. This location contains 
the size of fixed-length records or 
indicates the size of the largest record 
that currently exists in a file of 
variable-length records. 


F.HIBK 4 Indicates the highest virtual block number 
allocated. 


F.EFBK 4 Contains the end-of-file block number. 


The format of the block number is high-order 
word followed by low-order word. 


F.FFBY 2 Indicates the first free byte in the last 
block, or the maximum block size _ for 
magnetic tape. 


F.RACC 1 Record access byte. Bits 0 through 3 of 
this byte define the record access modes, as 
follows: 


Bit 0 = 1 to indicate READS/WRITES mode 
(FD.RWM); otherwise, it is 0 to indicate 
GETS/PUTS mode. 
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Table A-1l (Cont.) 
FDB Offset Definitions 


Symbolic Size Contents 


Offset (in bytes) 
Name 


Bit 1 = 1 to indicate random access mode 
(FD.RAN) for GETS /PUTS record I/0; 
otherwise, it is 0 to indicate sequential 
access mode. 


Bit 2 = 1 to indicate locate mode 
(FD. PLC) for GETS /PUTS record I/0; 
otherwise, it is 0 to indicate move mode. 


Bit 3 = 1 to indicate that PUTS operation 
in sequential mode does not truncate the 
file (FD.INS); otherwise, it is 0 to 
indicate that PUTS operation in 
sequential mode truncates the file. 


F.RCTL 1 Device characteristics byte. Bits 0 through 
5 define the characteristics of the device 
associated with the file, as follows: 


Bit 0 = 1 to indicate a record-oriented 
device (FD.REC), for example, a 
teletypewriter or line printer; a value 
of 0 indicates a block-oriented device, 
for example, a disk or DECtape. 


Bit 1 = 1 to indicate a carriage control 
device (FD.CCL); otherwise, it is 0. 


Bit 2 = 1 to indicate a teleprinter 
device (FD.TTY); otherwise, it is 0. 


Bit 3 = 1 to indicate a directory device 
(FD.DIR); otherwise, it is 0. 


Bit 4 = 1 to indicate a single directory 
device (FD.SDI). An MFD is used, but no 
UFDs are present. 


Bit 5 = 1 to indicate a _ block-oriented 
device that is inherently sequential in 
nature (FD.SQD), such as magnetic tape. 
A record-oriented device is assumed to be 
sequential in nature; therefore, this bit 
is not set for such devices. 


Bit 6 = 1 to indicate input spooling 
(FD.ISP). 
Bit 7 = 1 to indicate output spooling 
(FD.OSP). 
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Table A-1l (Cont.) 
FDB Offset Definitions 


Symbolic Size Contents 
Offset (in bytes) 
Name 
Bit 8 = 1 for DIGITAL use (FD.PSE). 
Bit 9 = 1 for DIGITAL use (FD.COM). 
Bit 10 = 1 for DIGITAL use (FD.F11). 
Bit 11 = 1 for DIGITAL use (FD.MNT). 
F.BKDS 4 Contains the block I/O buffer descriptor. 
or 
F.URBD Contains the user record buffer descriptor. 
F.NRBD 4 Contains the next record buffer descriptor. 
The record buffer descriptor contains the 
size of the buffer in the first word and the 
address of the buffer in the second word. 
or 
F.BKST 2 Contains the address of the I/O status block 
and for block I/O. 
F.BKDN 2 Contains the address of the AST service 
routine for block I/0. 
F.OVBS 2 Override block buffer size. This field has 
or meaning only before the file is opened. 
F.NREC 2 Contains the address of the next record in 
the block. 
F.EOBB 2 Contains a value defining the end-of-block 
buffer. 
F.RCNM 4 Contains the number of the record for random 
Or access operations. The format of the record 
number is the high-order word followed by 
the low-order word. 
F.CNTG 2 Contains a numeric value defining the number 
and of blocks to be allocated in creating a new 
file. This cell has meaning only before the 
file is opened. A value of OQ means’ leave 
the file empty; a positive value means 
allocate the specified number of blocks as a 
contiguous area and make the file 
contiguous; a negative value means allocate 
the specified number of blocks as a 
noncontiguous area and make the file 
noncontiguous. 
F.STBK 2 Contains the address of the statistics block 


in your program. 
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Table A-1 (Cont.) 
FDB Offset Definitions 


Symbolic Size Contents 

Offset (in bytes) 

Name 

F.ALOC 2 Contains the number of blocks to be 


allocated when the file must be extended. A 
positive (+) value indicates contiguous 
extend, and a negative (-) value indicates 
noncontiguous extend. 


F.LUN 1 Contains the logical unit number associated 
with the FDB. 


F.FACC 1 File access byte. This byte indicates the 
access privileges for a file, as summarized 
below: 


Bit 0 = 1#if the file is accessed for 
reading only (FA.RD). 


Bit 1= 1if the file is accessed for 
writing (FA.WRT). 


Bit 2 = 1if the file is accessed for 
extending (FA.EXT). 


Bit 3 = 1 if a new file is being created 
(FA.CRE); otherwise, it is 0 to indicate 
an existing file. 


Bit 4 = 1 if the file is a temporary file 
(FA.TMP). 


Bit 5=1 if the file is opened for 
shared access (FA.SHR). 


If Bit 3 above is 0: 


Bit 6 = 1 if an existing file is being 
appended (FA.APD). 


If Bit 3 above is ls: 


Bit 6 =1 if not superseding an 
existing file at file-create time 


(FA.NSP). 
F.DSPT 2 Contains the Dataset Descriptor pointer. 
F.DENB 2 Contains the default filename block pointer. 
F.BKEF 1 Contains the block I/0 event flag. 
F.EFN Contains the record I/O event flag. 
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Table A-1 (Cont.) 
FDB Offset Definitions 


Symbolic Size Contents 

Offset (in bytes) 

Name 

F.BKP1 1 Contains bookkeeping bits for FCS internal 
control. 

F.ERR 1 Error return code byte. A negative value 


indicates an error condition. 


F.ERR+1 1 Used in conjunction with F.ERR above. If 
F.ERR is negative, the following applies: 


F.ERR+1 = 0 to indicate that error code 
is an I/O error code (see error codes in 
Appendix I). 


F.ERR+1 = negative value to indicate that 
error code is a Directive Status Word 
error code (see DRERRS error codes in 
Appendix I). 


F.MBCT 1 Indicates the number of buffers to be used 
for multiple buffering. 


F.MBC1 1 Indicates the actual number of buffers 
currently in use if the multibuffering 
version of FCS is in use. 


F.MBFG I Multibuffering flag word. Contains either 
one of the multibuffering flags, as follows: 
Bit 0 = 1 to indicate read-ahead 
(FD.RAH). 
Bit 1 = 1 to indicate write-behind 
(FD.WBH). 
F.BGBC 1 Big-buffer block count in number of blocks 


if the big-buffer version of FCS is in use. 


Buffer offset for reading ANSI magnetic tape 
in record mode. 


F.VBSZ 2 Device buffer size word. Contains the 
virtual block size (in bytes). 


F.BBFS 2 Indicates the block buffer size. 

F.BKVB 4 Contains the virtual block number in the 
or user program for block I/O. 

F.VBN Contains the virtual block number. The 


format of the virtual block number is the 
high-order word followed by the low-order 
word. 


(Continued on next page) 


Symbolic Size 


Offset (in bytes) 
Name 

F.BDB 2 
F.EXT 2 
F.FLG 1 
E.CHR 1 
F.ACTL 2 
F.SEQN 2 
F.FNB - 


FILE DESCRIPTOR BLOCK 


Table A-1 (Cont.) 
FDB Offset Definitions 


Contents 


Contains the address of the block buffer 
descriptor block. This location always 
contains a nonzero value if the file is open 
and 0 if the file is closed. 


Address of FDB extension. 
Flag byte. 
Volume characteristics byte. 


Bit 0 = 1 to indicate ANSI magnetic tape 
formats D or F. 


The low-order byte of this word indicates 
the number of retrieval pointers to be used 
for the file. 


The control bits are in the high-order byte 
and are defined as follows. 


Bit 15 = 1 to specify that control 
information is to be taken from F.ACTL 
(FA.ENB). 


Bit 12 = 0 to cause positioning to the 
end of a magnetic tape volume set upon 
open or close. 


Bit 12 = 1 to cause positioning of a 
Magnetic tape volume set to just past the 
most recently closed file when the next 
file is opened (FA.POS). 


Bit 112+ 1 to cause a magnetic tape 
volume set to be rewound upon open or 
close (FA.RWD). 


Bit 9 = 1to cause a file not to be 
locked if it is not properly closed when 
accessed for write (FA.DLK). 


Contains the sequence number for sequenced 
records. 


The symbolic offset of the beginning of the 
filename block portion of the FDB. 


The format of a fi 


APPENDIX B 


FILENAME BLOCK 


lename block is illustrated in Figure B-l. The 
offsets within the filename block are described in Table B-1l. 


The offset names in a filename block may be defined either locally 
globally, as shown below: 
NBOF SL ;DEFINE OFFSETS LOCALLY. 
NBOFFS$S DEFSL ;DEFINE OFFSETS LOCALLY. 
NBOFF$ DEFSG ;DEFINE OFFSETS GLOBALLY. 
NOTE 
When you refer to filename block locations, it is 
essential to use the symbolic offset names, 
rather than the actual addresses of such 
locations. The position of information within 
the filename block may change from release to 
release, whereas the offset NMames remain 
constant. 
Table B-1l 
Filename Block Offset Definitions 
Symbolic Size Contents 
Offset (in bytes) 
Name 
N.FID 6 File identification field 
N.FNAM 6 File name field; specified as nine 
characters that are stored in Radix-50 
format 
N.FTYP 2 File type field; specified as three 
characters that are stored in Radix-50 
format 
N.FVER 2 File version number field (binary) 
N.STAT 2 Filename block status word (See bit 


definitions in Table B-2.) 


or 


(Continued on next page) 


FILENAME BLOCK 


Table B-1l (Cont.) 
Filename Block Offset Definitions 


Symbolic Size Contents 

Offset (in bytes) 

Name 

N.NEXT 2 Context for next .FIND operation 
N.DID 6 Directory identification field 
N.DVNM 2 ASCII device name field 

N.UNIT 2 Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) in the 
File Descriptor Block (FDB) and their significance are described in 


Table B-2. 
Same 
——— 


N.FTYP 


CUMULATIVE 
16 LENGTH IN 
BYTES (OCTAL) 


ZK-301-81 


Figure B-l Fiiename Block Format 


FILENAME BLOCK 


Table B-2 
Filename Block Status Word (N.STAT) 


Symbolic Value 


Offset (in octal) Meaning 

Name 

NB.VER 1 1 Set if explicit file version number is 
specified. 

NB.TYP 1 2 Set if explicit file type is specified 

NB.NAM 1 4 Set if explicit file name is specified 

NB.SVR 10 Set if wildcard file version number is 
specified 

NB.STP 20 Set if wildcard file type is specified 

NB.SNM 40 Set if wildcard file name is specified 

NB.DIR 1 100 Set if explicit directory string (UIC) is 
specified 

NB.DEV 1 200 Set if explicit device name string is 
specified 

NB.SD1 2 400 Set if group portion of UIC contains 
wildcard specification 

NB.SD2 2 1000 Set if owner portion of UIC contains 
wildcard specification 

NB.ANS 2000 Set if file name is in ANSI format. 

NB.WCH 4000 Set if wild character processing is 


required. 


NOTE 


Other bits are set as required by FCS 
and PIP for processing. 


l. Indicates bits that are set if the associated information is 
supplied through an ASCII dataset descriptor. 


2. Although NB.SD1 and NB.SD2 are defined, they are neither set 
nor supported by FCS. 


FILENAME BLOCK 


The filename block format for ANSI magnetic tape file names 


in Figure B-2. 


ZK-302-81 


Figure B-~2 ANSI Filename Block Format 


is 


shown 


The filename block offset definitions for ANSI magnetic tape are shown 


in Table B-3. 


Filename Block Offset Definitions for ANSI Magnetic Tape 


Symbolic Size 
Offset (in bytes) 
Name 

N.FID 2 
N.ANM1 12 
N.FVER 2 
N.STAT 2 
N.NEXT 2 
N.ANM2 6 
N.DVNM 2 
N.UNIT 2 


Table B-3 


Definition 


File identification field 
First 12 bytes of ANSI filename string 
File version number field (binary) 


Filename block status word (See 
definitions in Table B-2.) 


Context for next .FIND operation 
Remainder of the ANSI filename string 
ASCII device name field 


Unit number field (binary) 


bit 


APPENDIX C 


SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES 


Table C-l contains a summary of the I/0-related system directives in 
alphabetical order for ready reference. The parameters that may be 
specified with a directive are also described in the order of their 
appearance in the directive. These directives are described in detail 
in the RSX-11M/M-PLUS and Micro/RSX Executive Reference Manual. 


EES ES AS A LS 


Table C-l 
Summary of I/0-Related System Directives 


Directive Function and Parameters 


ALUNS Assign Logical Unit Number -- Assigns a logical unit 
number to a physical device. 
Syntax 


ALUNS lun,dev,unt 


lun Logical unit number 


dev Physical device name (two ASCII characters) 
unt = Physical device unit number 
GLUNS Get Logical Unit Number Information -- Fills a 6-word 
buffer with information about a physical unit to which 
the LUN is assigned. 
Syntax 


GLUNS lun,buf 


lun Logical unit number 


buf Address of a 6-word buffer in which the LUN 


information is to be stored 
GMCRS$ Get MCR Command Line -- Transfers an 80-byte MCR command 
line to the task issuing GMCRS. No parameters are 
required in this Directive. 
QIOS Queue I/O Request -- Places an I/O request in the device 
queue associated with the specified logical unit number. 


(Continued on next page) 


SUMMARY OF I/0-RELATED SYSTEM DIRECTIVES 


Table C-1 (Cont.) 
Summary of I/0-Related System Directives 


Directive Function and Parameters 


Syntax 
QIOS$ fnc,lun,efn,pri,isb,ast,prl 
fnce = I/O function code 
lun = Logical unit number 
efn = Event flag number 


pri = Priority of the request (ignored but must be 
present) 


isb = Address of the I/O status block 


ast = Entry-point address of the AST service 
routine 


prl = Parameter list in the form <Pl,...,P6> 
QIOWS Queue I/O Request and Wait -- Places an I/O request in 

the device queue associated with the specified logical 
unit number. The Executive suspends the task until the 
specified event flag is set. 
Syntax 

QIOWS fnc,lun,efn,pri,isb,ast,prl 

fne = I/O function code 

lun = Logical unit number 


efn = Event flag number 


pri = Priority of the request (ignored but must be 
present) 


isb = Address of the I/O status block 


ast = Entry-point address of the AST service 
routine 


prl = Parameter list in the form <Pl,...,P6> 


RCSTS Receive Data or Stop -- Instructs the system to dequeue 
a 13-word data block for the task issuing RCSTS; the 
data block was queued for the task with a Send Data 
directive (SDATS$) or a Send, Request, and Connect 
directive (SDRCS). 


(Continued on next page) 
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Table C-1 (Cont.) 
Summary of I/0-Related System Directives 


Directive Function and Parameters 


Syntax 
RCSTS tname,buf 


tname = Name of the sending task (if not specified, 
data may be received from any task) 


buf = Address of a 15-word buffer to receive the 
sender task name and data 


RCVDS$ Receive Data -- Receives a 13-word data block that has 
been queued (FIFO) by a Send Data directive (see SDATS 
and SDRCS which follow). 

Syntax 
RCVDS tsk,buf 


tsk = Name of the sending task 


buf = Address of the 15-word data buffer (2-word 
sending task name and 13-word data block) 


RCVXS Receive Data or Exit -- Receives a 13-word data block if 
queued by a Send Data directive (see SDATS and SDRCS 
following), or the task exits if no data is queued. 

‘Syntax 
RCVXS tsk,buf 


tsk = Name of the sending task (if not specified, 
data may be received from any task) 


buf = Address of the 15-word data buffer (2-word 
sending task name and 13-word data block) 


SDATS Send Data -- Queues (FIFO) a 13-word block of data for a 
task to receive, and declares a significant event. 


Syntax 
SDATS tsk,buf,efn 
tsk = Name of the receiving task 


buf Address of the 13-word data buffer 


efn = Event flag number 


SDRCS$ Send, Request, and Connect -- Executes a Send Data 
directive to the specified task, requests the Executive 
to activate the task if it is not already active, and 
then connects to the task. 


(Continued on next page) 
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Table C-1 (Cont.) 
Summary of I/0-Related System Directives 


Directive Function and Parameters 


SDRP$ 


Syntax 
SDRCS tname,buf,efn,east 


tname = Target task name of the offspring task to 
be connected 


buf = Address of a 13-word send buffer 


efn = The event flag to be cleared on issuance 
and set when the offspring task exits or 
emits status 


east = Address of an AST routine to be called when 
the offspring task exits or emits status 


Send Data Request and Pass Offspring Control Block -- 
Sends a data packet for the specified task, chains to 
the requested task, and requests it if it is not already 
active. 


Syntax 
SDRPS task,bufadr,buflen,efn,flag 
task = Name of the task to be chained to 


bufadr = Address of the buffer to be given to the 
requested task 


buflen = Length of the buffer to be given to. the 
requested task 


efn = Event flag 


flag = Flags byte controlling the execution of 
this directive. The flag bits are defined 
as follows: 


SD.REX = 128. Force this task to exit 
upon successful completion of 
this directive 


SD.RAL = l. Pass all connections’ to 
the requested task (default is 
pass none). If you specify 


this flag, do not specify the 
parent task name. 


NOTE 


The target task may not 
be a CLI task. 
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SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES 


Table C-1l1 (Cont.) 
Summary of I/0-Related System Directives 


Directive Function and Parameters 


SD.RNX = 2. Pass the first connection 
in the queue, if there is one, 
to the requested task. If you 
specify this flag, do not 
specify the parent task name. 


SMSGS$ Send Message -- Creates and _ sends a 
formatted data packet to a system-defined target task. 
The only valid target for the Send Message directive is 
the Error Logger. The task that issues the SMSGS 
directive must be privileged. 
Syntax 
SMSGS tgt,buf,len,<pri,...,prn> 


tgt = Target identifier 


buf Address of optional data buffer 


Length in bytes of optional data 
buffer 


len 


<pri,...,prn> = Target-specified parameter list 


VRCDS Variable Receive Data -- Instructs’ the 
system to dequeue a variable-length data block for the 
task issuing VRCDS. The block was queued by the 
Variable Send Data directive. If you specify the 
sending task, only data sent by that task is received. 


Syntax 
VRCDS task,bufadr,buflen 
task = Sender task name 
bufadr = Buffer address 


buflen = Buffer size in words (256. words 
maximum). The default is 13. words. The 
first two words are the sender task name. 
The data block follows. 


VRCSS Variable Receive Data or Stop -- Instructs 
the system to dequeue a variable-length data block for 
the task issuing VRCSS. The block was queued by a 
Variable Send Data directive. If there is no packet, 
the task issuing VRCSS$ is stopped. The sending task is 
expected to issue an Unstop directive after sending the 
data. When you specify a sender task, only data sent by 
that task is received. 


Syntax 
VRCSS$ task,bufadr,buflen 
task = Sender task name 
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Table C-1 (Cont.) 
Summary of I1/0-Related System Directives 


Directive Function and Parameters 


bufadr = Buffer address 


buflen = Buffer size in words (256. words 
maximum). The default is 13. words. The 
first two words are the sender task name. 
The data block follows. 


VRCXS Variable Receive Data or Exit -- Instructs 
the system to dequeue a variable-length data block for 
the issuing task. The data block was queued for’ the 
task by a Variable Send Data directive. If you specify 
a sender task, only data sent by that task is received. 
If no data has been sent to the task issuing VRCXS, the 
task exits. 


Syntax 
VRCXS task,bufadr,buflen 
task = The name of the sending task 


bufadr = The buffer address 


buflen = The buffer length (a maximum of 256. 
words). The default is a minimum of 13. 
words. The first two words are the sender 
task name. 
VSDAS$ Variable Send Data -- Instructs the system 
to queue a variable-length data block for the specified 
task to receive. If you specify an event flag, a 
significant event is declared when the directive 


executes successfully. 

Syntax 
VSDAS task,bufadr,buflen 
task = Receiving task name 
bufadr = Buffer address 


buflen = Buffer size in words (a maximum of 256. 
words). The default is 13. words. 


VSRCS$ Variable Send, Request, and Connect -- 
Performs a Variable Send Data to the specified task, 
requests the task if it is not already active, and then 
connects to the task. 

Syntax 
VSRCS tname,buf,buflen,efn,east,esb 
tname = Target task name of the offspring task to 


be connected 


(Continued on next page) 


Directive 


SUMMARY OF 


Summary of 


buf = 


buflen = 


efn = 


east = 


esb = 


I/O-RELATED SYSTEM DIRECTIVES 


Table C-1 (Cont.) 
I/O-Related System Directives 


Function and Parameters 


Address of send buffer 


Length of the buffer (a maximum of 256. 
words). The default is 13. words. 


The event flag cleared when the directive 
is issued and set when the offspring task 
exits or emits status 


Address of an AST routine to be called 
when the offspring task exits or emits 
status 


Address of an 8-word status block to be 
written when the offspring task exits or 
emits status: 


Word 0 -- Offspring task exit status 
Word 1 -- TKTN abort code 
Words 2-7 -- Reserved 


off 


in CRCOPY. 


FDBOUT: 


FDBIN: 


RECBUF : 
OFNAM: 
IFNAM: 
START: 


GTREC: 


108: 


-TITLE 
-MCALL 
-MCALL 
-MCALL 
INLUN=3 


OUTLUN=4 


FSRSZS$ 
FDBDFS 
FDATSA 
FDRCSA 
FDOPSA 
FDBDFS$ 
FDRCSA 
FDOPSA 
- BLKB 
NMBLKS 
NMBLKS 
FINITS 
OPENSR 
BCS 
OPEN SW 
BCS 
GETS 
BCS 
MOV 
MOV 
ADD 

CM PB 
BNE 
SOB 


APPENDIX D 


SAMPLE PROGRAMS 


The sample programs that follow read records 
any blanks to the right of the data portion of the record, 
While the programs are 
card reader input and printer output, device 


and write the data record on an output device. 
intended primarily for 
independence is maintained. 


The main program is CRCOPY; CRCOPA and CRCOPB are variations. 
a Dataset Descriptor instead of the default filename block used 
CRCOPB uses run-time initialization of the FDB. 


CRCOPY 


from an 


;Card reader copy routine 


FDBDFS$,FDATSA,FDRCSA,FDOPSA,NMBLKS,FSRSZ$ 
OPENSR, OPENSW, GETS, PUT$, CLOSES, EXITSS 


FINITS 


2 


R.VAR,FD.CR 
, RECBUF, 80. 
OUTLUN, , OFNAM 


,RECBUF, 80. 
INLUN, , IFNAM 
80. 
OUTPUT , DAT 
INPUT,DAT 


#FDBIN 
ERROR 
#FDBOUT 
ERROR 
#FDBIN 
CKEOF 
F.NRBD (RO) ,R1 
#RECBUF,R2 
R1,R2 
#40,-—(R2) 
PTREC 
R1,10$ 


;Assign CR or file device 
sAssign to output device 


sAllocate space for output FDB 
sInit file attributes 

s;Init record attributes 

;Init file open section 
;Allocate space for input FDB 
;Init record attributes 

;Init file open section 
;Record buffer 

;Output filename 

;Input filename 

sInit file storage region 
;Open the input file 

sBranch if error 

;Open the output file 

;Branch if error 

;Note - URBD is all set up 
;Error should be EOF indication 
sRl=size of record read 


;R2=address of last byte+l 
;Strip trailing blanks 


;At this point, Rl contains the stripped size of the 


srecord to be written. 


If the card is blank, 


ra zero-length record is written. 


PTREC: 


ERROR: 


PUTS 
BCC 
NOP 


#FDBOUT, ,R1 
GTREC 


7Rl is needed to specify 
sthe record size. 
;Error code goes here 


input device, 


CRCOPA 


CKEOF: 


FDBOUT: 


FDBIN: 


RECBUF : 
CFDSPT: 


IFDSPT: 


ONAM: 


INAM: 


START: 


GTREC: 


SAMPLE PROGRAMS 


sEnd of file? 

sBranch if other error 
;Close the input file 
;Close the output file 


sIssue exit directive 


;Card reader copy routine 


FDBDF$,FDATSA,FDRCSA,FDOPSA,NMBLKS$,FSRSZS$ 
OPENSR,OPENSW, GETS, PUTS,CLOSES, EXITSS 


;Assign CR or file device 
;Assign to output device 


;Device descriptor 
;Directory descriptor 
;Filename descriptor 
;Device descriptor 
;Directory descriptor 
;Filename descriptor 


;Init file storage region 

;Open the input file 

sBranch if error 

;Open the output file 

sBranch if error 

;Note - URBD is all set up 
;Error should be EOF indication 
sRl=size of record read 


;R2=address of last byte+l 
;Strip trailing blanks 


CMPB #IE.EOF,F.ERR (RO) 
BNE ERROR 
CLOSES RO 

BCS ERROR 
CLOSE$ #FDBOUT 

BCS ERROR 

EXITSS 

. END START 

-TITLE CRCOPA 
.MCALL 

-MCALL 

-MCALL FINITS 
INLUN=3 

OUTLUN=4 

FSRSZS$S 2 

FDBDFS 

FDATSA R.VAR,FD.CR 
FDRCSA_ ,RECBUF,80. 
FDOPSA OUTLUN,OFDSPT 
FDBDFS 

FDRCSA’_ ,RECBUF,80. 
FDOPSA INLUN,IFDSPT 
- BLKB 80. 

. WORD 0,0 

.-WORD 0,0 

-WORD ONAMSZ , ONAM 
- WORD 0,0 

- WORD 0,0 

-WORD INAMSZ, INAM 
-ASCII /OUTPUT.DAT/ 
ONAMSZ=. -ONAM 

. EVEN 

-ASCII /INPUT.DAT/ 
INAMSZ=. -INAM 

. EVEN 

FINITS 

OPENSR #FDBIN 

BCS ERROR 
OPENSW #FDBOUT 

BCS ERROR 

GETS #FDBIN 

BCS CKEOF 

MOV F.NRBD (RO) ,R1 
MOV #RECBUF,R2 
ADD R1,R2 

CMPB #40,-(R2) 
BNE PTREC 

SOB R1,10$ 


;At this point, Rl contains the stripped size of the 


srecord to be written. 


If the card is blank, 


ja zero-length record is written. 


PTREC: 


ERROR: 
CKEOF: 


PUTS 
BCC 
NOP 
CMPB 
BNE 
CLOSES 


#FDBOUT, ,R1 
GTREC 


#IE.EOF,F.ERR (RO) 


ERROR 
RO 


;Rl is needed to specify 
sthe record size. 

;Error code goes here 
;End of file? 

sBranch if other error 
;Close the input file 


SAMPLE’ PROGRAMS 


BCS ERROR 

CLOSES #FDBOUT 7;Close the output file 
BCS ERROR 

EXITSS ;Issue exit directive 

- END START 

-TITLE CRCOPB ;Card reader copy routine 


-MCALL FDBDFS,FDATSA,FDRCSA,FDOPSA,NMBLKS,FSRSZ$ 
-MCALL OPENSR,OPENSW, GETS, PUTS,CLOSES, EXITSS 
-MCALL FINITS,FDATSR 


INLUN=3 sAssign CR or file device 
OUTLUN=4 ;Assign to output device 
FSRSZ$ 2 


FDBOUT: FDBDFS$ 
FDBIN: FDBDFS 
RECBUF: .BLKB 80. 


CFDSPT: .WORD 0,0 Device descriptor 
-WORD 0,0 ;Directory descriptor 
~WORD ONAMSZ , ONAM ;Filename descriptor 

IFDSPT: .WORD 0,0 ;Device descriptor 
«WORD 0,0 ;Directory descriptor 
» WORD INAMSZ, INAM ;Filename descriptor 


ONAM: eASCII /OUTPUT.DAT/ 
ONAMSZ=.—-ONAM 
- EVEN 

INAM: e-ASCII /INPUT.DAT/ 
INAMSZ=.-INAM 
- EVEN 

START: FINITS ;Init file storage region 
OPENSR' #FDBIN, #INLUN, #IFDSPT,, #RECBUF, #80. 

;Runtime initialization 

BCS ERROR sBranch if error 
FDATSR #FDBOUT,#R.VAR, #FD.CR ;Runtime initialization 
OPENSW RO, #OUTLUN, #OFDSPT,, #RECBUF, #80. 


BCS ERROR s;Branch if error 
GTREC: GETS #FDBIN ;Note - URBD is all set up 
BCS CKEOF 7;Error should be EOF indication 
MOV F.NRBD (RO) ,R1 sRl=size of record read 
MOV #RECBUF ,R2 
ADD R1,R2 ;R2=address of last byte+l 
10S: CM PB #40,-(R2) ;Strip trailing blanks 
BNE PTREC 
SOB R1,10$S 


;At this point, Rl contains the stripped size of the 
srecord to be written. If the card is blank, 
ra zero-length record is written. 


PTREC: PUTS #FDBOUT,,R1 ;Rl is needed to specify 
BCC GTREC the record size. 
ERROR: NOP ;Error code goes here 
CKEOF: CMPB #IE.EOF,F.ERR(RO) ;End of file? 
BNE ERROR ;Branch if other error 
CLOSES RO ;Close the input file 
BCS ERROR 
CLOSES #FDBOUT ;Close the output file 
BCS ERROR 
EXITSS ;Issue exit directive 
« END START 


APPENDIX E 


INDEX FILE FORMAT 


The index file ([{0,O0]INDEXF.SYS) of a Files-1l1 volume consists of 
virtual blocks, starting with virtual block 1, the bootstrap block. 
Virtual block 2 is the home block. The structure of an index file is 
shown below. 


Virtual Block Number Index File Element 

1 Bootstrap block 

2 Home block 

3 Index file bit map (n blocks); 
the value of n is in the home 
block 

3+n Index file header 

3+n+1 Storage map header 

3+n+2 Bad block file header 

3+n+3 Master File Directory header 

3+n+4 Checkpoint file header 

3+n+5 User file header 1 

3+n+6 User file header 2 


e e 
e e 


User file header n. 


E.1 BOOTSTRAP BLOCK 


A disk that is structured for Files-1l has a 256-word block, starting 
at physical block 0. This block contains either a bootstrap routine 
or a message to the operator stating that the volume does not’ contain 
a bootstrappable system. The bootstrap routine brings a core image 
into memory from a predefined location on the disk. 


E.2 HOME BLOCK 


The home block contains volume identification information that is 
formatted as shown in Table E-l. This block is located either in 
logical block 1 or at any even multiple of 256 blocks. 


E-1 


INDEX FILE FORMAT 


The offset names in the home block may be defined either locally or 
globally, as shown below. 


HMBOFS DEFSL ;DEFINES OFFSETS LOCALLY. 


HMBOF$ DEFSG ;DEFINES OFFSETS GLOBALLY. 


E.3 INDEX FILE BIT MAP 


The index file bit map controls the use of file header blocks in the 
index file. The bit map contains a bit for each file header block 
contained in the index file. The bit for a file header block is 
located by means of the file number of the file with which it is 
associated. The values of the bit map are as follows: 


0 - Indicates that the file header block is available. The file 
control primitives can use this block to create a file. 


1 - Indicates that the file header block is in use. This block 
has already been used to create a file. 


E.4 PREDEFINED FILE HEADER BLOCKS 
The first five file header blocks are described below. 
File Header Block Significance 


Index File Header This is the standard header associated 
with the index file. 


Storage Map File The storage map is a file that is used 
Header to control the assignment of disk blocks 
to files. 


Bad Block File The bad block file is a file that 
Header consists of unusable blocks (bad 
sectors) on the disk. 


Master File Directory This header block is associated with the 

Header Master File Directory for the disk. 
This directory contains entries for the 
index file, the storage map file, the 
bad block file, the Master File 
Directory (MFD), the checkpoint file, 
and all User File Directories (UFDs). 


Checkpoint File Header This block identifies the file that is 
used for the checkpoint areas for all 
checkpointable tasks. In RSX-ll, a task 
can also have checkpoint space in the 
task image itself. 


The remainder of the index file consists of file header blocks’ for 
user files, as shown in the list at the beginning of this section. 


INDEX FILE FORMAT 


Table E-1l 
Home Block Format 


Size Content Offset 
(in bytes) 
2 Index bit map size H.IBSZ 
4 Location of index bit H.IBLB 
map 
2 Maximum files allowed H.FMAX 
2 Storage bit map cluster H.SBCL 
factor 
2 Disk device type H.DVTY 
2 Structure level H.VLEV 
L2. Volume name (12 ASCII H. VNAM 
characters) . 
4 Reserved 
2 Volume owner's UIC H. VOWN 
2 Volume protection code H. VPRO 
2 Volume characteristics H.VCHA 
2 Default file protection H.DFPR 
word 
6 Reserved -- 
1 Default number of H.WISZ 
retrieval pointers 
in a window 
1 Default number of H.FIEX 
blocks to extend files 
1 Number of entries in H.LRUC 
directory LRU 
sig Available space -- 
2 Checksum of words 0-28 H.CHKl 
14. Creation date and time H.VDAT 
100. Volume header label (not -- 
used) 
82. System-specific infor- -- 
mation (not used) 
254. Relative volume table -< 
(not used) 
2 Checksum of home block H.CHK2 


(Words O through 255) 


APPENDIX F 
FILE HEADER BLOCK FORMAT 
block. 


Table F-l shows the format of the file header 


areas within the file header block are described in detail in the 
following sections. The offset names_in the file header block may be 
defined either locally or globally, as shown in the following 
statements: 
FHDOFS DEFSL *;DEFINE OFFSETS LOCALLY. 
FHDOFS$ DEFSG ;DEFINE OFFSETS GLOBALLY. 
Table F-1 
File Header Block 
Area Size Content Offset 
(in bytes) 
Header Area 1 Identification area offset H.IDOF 
in words 
1 Map area offset in words H.MPOF 
2 File number H.FNUM 
2 File sequence number H.FSEQ 
2 Structure level and system H.FLEV 
number 
- Offset to file owner H.FOWN 
information, consisting of 
member number and group 
number 
wd Member number H. PROG 
1 Group number H. PROJ 
2 File protection code H.FPRO 
1 User-controlled file H.UCHA 
characteristics 


(Continued on next page) 


various 
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Table F-1 (Cont.) 
File Header Block 


Area Size 
(in bytes) 


32. 


Identification 6 
Area 


Map Area 1 


Content 


System-controlled file 
characteristics 


User file attributes 


Size in bytes of header 
area of file header block 


File name (Radix-50) 
File type (Radix-50) 


File version number 
(binary) 


Revision number 
Revision date 
Revision time 
Creation date 
Creation time 
Expiration date 


To round up to word 
boundary 


Size (in bytes) of 
identification area of 
file header block 


Extension segment number 


Extension relative volume 
number (not implemented) 


Extension file number 


Extension file sequence 
number 


Size (in bytes) of the 
block count field of a 


retrieval pointer (1 or 2); 


only 1 is used 


Size (in bytes) of the 


logical block number field 


of a retrieval pointer (2, 
3, or 4); only 3 is used 


(Continued on next page) 


Offset 


H.SCHA 


H.UFAT 


S.HDHD 


I.FNAM 


I.FTYP 


I.FVER 


I.RVNO 
I.RVDT 
I.RVTI 
I.CRDT 
I.CRTI 


I. EXDT 


S.IDHD 


M.ESQN 


M.ERVN 


M.EFNU 


M.EFSQ 


M.CTSZ 


M.LBSZ 


Area 
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Table F-1 (Cont.) 
File Header Block 


Size Content Offset 


(in bytes) 


Checksum Word 


1 Words of retrieval pointers M.USE 


in use in the map area 


1 Maximum number of words M.MAX 


of retrieval pointers 
available in the map area 


- Start of retrieval pointers M.RTRV 


- Size in bytes of map area S.MPHD 
of file header block 

2 Checksum of words 0 through H.CKSM 
255 
NOTE 


The checksum word is the last word of the file header 
block. Retrieval pointers occupy the space from the 
end of the map area to the checksum word. 


F.1 HEADER AREA 


The information in the header area of the file header block consists 


of the following: 


Identification area 
offset 


Map area offset 


File number 


File sequence number 


Structure level 


File owner 
information 


Word 0, bits 0-7. This byte locates the start 
of the identification area relative to the 
start of the file header block. This offset 
contains the number of words from the start of 
the header to the identification area. 


Word 0, bits 8-15. This byte locates the start 
of the map area relative to the start of the 
file header block. This offset contains’ the 
number of words from the start of the header 
area to the map area. 


The file number defines the position this file 
header block occupies in the index file; for 
example, the index file is number 1, the 
storage bit map is file number 2, and so forth. 


The file number and the file sequence number 
constitute the file identification number used 
by the system. This number is different each 
time a header is reused. 


This word identifies the system that created 
the file and indicates the file structure. A 
value of [1,1] is associated with all current 
Files-1l volumes. 


This word contains the group number and owner 
number constituting the User Identification 


F-3 


File protection code 


File characteristics 


User file 
attributes 
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Code (UIC) for the file. Legal UICs are within 
the range [l,l] to [377,377]. UIC [1,1] is 
reserved for the system. 


This word specifies the manner in which the 
file can be used and who can use it. When 
creating the file, you specify the extent of 
protection desired for the file. 


This word, consisting of two bytes, defines the 
status of the file. 


Byte 0 defines the user-controlled characteris- 
tics, as follows: 


UC.CON = 200 - Logically contiguous file. 
When the file is extended (for example, by a 
WRITES or PUTS macro), bit UC.CON is cleared 
whether or not the extension requests 
contiguous blocks. 


UC.DLK = 100 - File improperly closed. 


Byte 1 defines system-controlled 
characteristics, as follows: 


SC.MDL = 200 - File marked for delete 
SC.BAD = 100 - Bad data block in file 


This area consists of 16 words. The first 
seven words of this area are a direct image of 
the first seven words of the FDB when the file 
is opened. The other nine words of the’ record 
I/O control area are not used by FCS, although 
RMS does use them. 


F.2 IDENTIFICATION AREA 


The information in the identification area of the file header block 
consists of the following: 


File name 


File type 


File version number 


Revision number 


Revision date 


The file's creator specifies a file name of up 
to nine Radix-50 characters in length. This 
name is placed in the name field. The unused 
portion of the field (if any) is zero-filled. 


This word contains the file type in Radix-50 
format. 


This word contains the file version number, in 
binary, as specified by the creator of the 
file. 


This word is initialized to 0 when the file is 
created; it is incremented each time a file is 
closed after being updated or modified. 


Seven bytes are used to maintain the date on 
which the file was last revised. The revision 
date is kept in ASCII form in the format day, 
month, year (two bytes, three bytes, and two 
bytes, respectively). This date is meaningful 
only if the revision number is a nonzero value. 


F-4 
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Revision time Six bytes are used to record the time at which 
the file was last revised. This information is 
recorded in ASCII form in the format hour, 
Minute, and second (two bytes each). 


Creation date The date on which the file was created is kept 
in a 7-byte field having the same format as 
that of the revision date (see above). 


Creation time The time of the file's creation is maintained 
in a 6-byte field having the same format as 
that of the revision time (see above). 


Expiration date The date on which the file becomes eligible to 
be deleted is kept in a 7-byte field having the 
same format as that of the revision date (see 
above). Use of expiration-is not implemented. 


F.3 MAP AREA 


The map area contains the information necessary to map virtual block 
numbers to logical block numbers. This is done by means of pointers, 
each of which points to an area of contiguous’ blocks. A pointer 
consists of a count field and a number field. The count field defines 
the number of blocks contained in the contiguous area pointed to, and 
the logical block number (LBN) field defines the block number of the 
first logical block in the area. 


A value of n in the count field (see below) means that n+l blocks are 
allocated, starting at the specified block number. 


The retrieval pointer format used in the Files-1l1 file structure is 


shown below: 
15 0 
COUNT-1 HIGH LBN 


LOW LBN 


Z2K-303-81 


NOTE 


The remaining paragraphs in this appendix apply to 
RSX-11M/M-PLUS and Micro/RSX systems that support the 
multiheader version of F11ACP. 


The map area normally has space for 102 retrieval pointers. It can 
map up to 102 discontiguous segments or up to 26112 blocks if the file 
is contiguous. If more retrieval pointers are required because the 
file is too large or consists of too many discontiguous segments, 
extension headers are allocated to hold additional retrieval pointers. 
Extension headers are allocated within the index file. They are 
identified by a file number and a file sequence as are other file 
headers; however, extension file headers do not appear in any 
directory. 
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A nonzero value in the extension file number field of the map area 
indicates that an extension header exists. The extension header is 
identified by the extension file number and the extension file 
sequence number. The extension segment number numbers the headers of 
the file sequentially, starting with a 0 for the first. 


Extension headers of a file contain a header area and identification 
area that are a copy of the first header as it appeared when the first 
extension was created. Extension headers are not updated when the 
first header of the file is modified. 


Extension headers are created and handled by the file control 
primitives as needed; their use is transparent to you. 


APPENDIX G 


SUPPORT OF ANSI MAGNETIC TAPE STANDARD 


This appendix defines the ANSI magnetic tape labeling standard, which 
is a level three implementation of the ANSI standard Magnetic Tape 
Labels and File Structure for Information Interchange (X3.27-1978). 
The exceptions are that ANSI does not support spanned records and that 
DIGITAL's tape system does not support user~supplied labels. 
User-supplied labels may appear on a tape; however, they are 
accessible to application programs through the unlabeled tape feature 
only. 


G.1 VOLUME AND FILE LABELS 


Tables G-l, G-2, G-3, and G-4 present the format of volume labels and 
file header labels. 


G.1.1 Volume Label Format 


Table G-l 
Volume Label Format 


Character Length 
Position Field Name (in bytes) Contents 
1-3 Label identifier 3 VOL 
4 Label number 1 1 
5-10 Volume identifier 6 Volume label. Any ANSI "a" 
character. An "a" character 
is defined by the ANSI 
standard as any of the 
uppercase letters A through 
Z, the digits 0 through 9, 
and the following special 
characters: space ! "%& ' 
()- 8 ty Ha SS ge Ke? 
11 Accessibility 1 Any ANSI "a" character. A 


space indicates no 


restriction. You can specify 
the "a" character with the 


(Continued on next page) 
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Table G-l (Cont.) 
Volume Label Format 


Character Length 
Position Field Name (in bytes) Contents 
/VOLUME_ACCESSABILITY:"c" 
qualifier in the DCL 
INITIALIZE commands. Any 
ANSI wat character is 
allowed. The default 
character is a space. Refer 
to the RSX~11M/M-PLUS MCR 
Operations Manual or 
RSX-11M/M-PLUS Command 
Language Manual for more 
information on INITIALIZE. 
12-37 Reserved 26 Spaces 
38-51 Owner 14 The contents of this field 
identification are system dependent and are 
used for volume protection 
purposes. See Section 
G.1.1.1 below. 
52-79 Reserved 28 Spaces. 
80 Label standard 1 3 
version 
G.1.1.1 Contents of Owner Identification Field - The owner 


identification field is divided into the following three subfields and 
a Single pad character: 


1. System identification (positions 38 through 40) 
2. Volume protection code (positions 41 through 44) 
3. UIC (positions 45 through 50) 


4. A numeric 1 (position 51) 


The system identification consists of the following character 
sequence: 
Dx 

x The machine code, which can be one of the following: 

8 - PDP-8 

A - DECsystem-10 

B - PDP-1l 

F - PDP-15 


The D%x characters provide an identification method so that’ the 
remaining data in the owner identification field can be interpreted. 
The /OWNER switch to the MCR INI command allows you to overwrite these 
characters. The /OWNER="owner" qualifier to the DCL INITIALIZE 
command allows you to overwrite these characters. (Refer to the 
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RSX-11M/M-PLUS MCR Operations Manual and the RSX-11M/M-PLUS Command 
Language Manual for more information.) In the case of tapes produced 
on PDP-11 systems, the default system identification is D%B and_ the 
volume protection code and UIC are interpreted as described below. 


The volume protection code in positions 41 through 44 defines access 
protection for the volume for four classes of users. Each class of 
user has access privileges specified in one of the four columns, as 
follows: 


Position Class 
41 System (UIC no greater than [7,255]) 
42 Owner (group and member numbers match) 
43 Group (group number matches) 
44 World (any user not in one of the above) 


One of the following access codes can be specified for each character 
position: 


Code Privilege 
0 No access 
a Read access only 
2 Extend (append) access 
3 Read/extend access 
4 Total access 


The UIC is specified in character positions 45 through 50. The first 
three characters are the group code in decimal. The next three are 
the user code in decimal. 
The last character in the owner identification field is a numeric l. 
The following is an example of the owner identification field. 
Owner identifier - D%B14100631461 
1. The file was created on a PDP-1l. 
2. System and group have read access. 
Owner has total access. 


All others are denied access. 


3. The UIC is [063,146]. 


G.1.2 User Volume Labels 


User volume labels are never written or passed back to you. If 
present, they are skipped. 


G.1.3 File Header Labels 


The following information should be kept in mind when creating file 
header labels: 


e The Files-11 naming convention uses a subset (Radix-50) of the 
available ANSI character set for file identifiers. 


@ One character in the file identifier, the period (.), is fixed 
by Files-1l. 
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A maximum of 13 of the 17 bytes in the file identifier are 
processed by Files-ll. 


It is strongly recommended that all file identifiers be 
limited to the Radix-50 PDP-1l character set, and that no 
character other than the period (.) be used in the file type 
delimiter position for data interchange between PDP-11 and 
DECsystem-10 systems. 


For data interchange between DIGITAL and non-DIGITAL systems, 


the conventions listed above should be followed. If they are 
not, refer to Section G.1.3.1. 


Tables G-2, G-3, and G-4 describe the HDR1, HDR2, and HDR3 _ labels, 


respectively. 
Table G-2 
File Header Label (HDR1) 
Character Length 
Position Field Name (in bytes) Contents 
1-3 Label identifier 3 HDR 
4 Label number 1 1 
5-21 File identifier 17 Any ANSI "a" character. See 
Table G-l. 
22-27 File set 6 Volume identifier of the 
identifier first volume in the set of 
volumes. 
28-31 File section 4 Numeric characters. This 
number field starts at 0001 and is 
increased by 1 for each 
additional volume used by 
the file. 
32-35 File sequence 4 File number within the 
number volume set for this file. 
This number starts at 0001. 
36-39 Generation number 4 Numeric characters. 
40-41 Generation version 2 Numeric characters. 
42-47 Creation date 6 _yyddd (_ indicates space) 
or 
_00000 if no date. 
48-53 Expiration date 6 Same format as creation 
date. 
54 Accessibility 1 Space. 
55-60 Block count 6 000000 


(Continued on next page) 
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Table G-2 (Cont.) 
File Header Label (HDR1) 


Character Length 
Position Field Name (in bytes) Contents 
61-73 System code 13 The three letters DEC, 
followed by the name of the 
system that produced the 
volume. See Section 
G.1.1.1. 
Examples: DECFILE1I1A 
DECSYSTEM10 
Pad name with spaces. 
74-80 Reserved 7 Spaces. 
Table G-3 


File Header Label (HDR2) 


Character Length 
Position Field Name (in bytes) Contents 
1-3 Label identifier 3 HDR 
4 Label number 1 2 
5 Record format 1 F - Fixed length 
D - Variable length 
S - Spanned 
U - Undefined 
6-10 Block length 5 Numeric characters. 
11-15 Record length 5 Numeric characters. 
16-50 System-dependent 35 Positions 16 through 36 are 
information spaces. 


Position 37 defines carriage 
control and can contain one 
of the following: 


A - First byte of 
record contains 
FORTRAN control 
characters. 


Space - line feed/carriage 
return is to be 


inserted between 
records. 
M - the record contains 


all form control 
information. 


(Continued on next page) 
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Table G-3 (Cont.) 
File Header Label (HDR2) 


Character Length 

Position Field Name (in bytes) Contents 
If DEC appears in positions 
61 through 63 of HDR1, 
position 37 must be as 
specified above. 
Positions 38 through 50 
contain spaces. 

51-52 Buffer offset 2 Numeric characters. 00 on 
tapes produced by Files-1ll. 
Supported only on input’ to 
Files-1l. 

53-80 Reserved 28 Spaces. 

Table G-4 


File Header Label (HDR3) 


Character Length 
Position Field Name (in bytes) Contents 
1-3 Label identifier 3 HDR 
4 Label number i Ie 3 
5-68 System-dependent 64 File attributes specified at 


> creation time. Each of the 
32 bytes of user file 
attributes is expanded into 
two hexadecimal characters. 
The first seven words of this 
area are a direct image of 
the first seven words of the 
FDB when the file is opened. 
These are the same words in 
the file attribute section of 
the File Descriptor Block 
given in Appendix A. The 
other nine words are not used 
by FCS though they are used 
by RMS. 


The following list translates 
the user file attribute bytes 
to the corresponding 
hexadecimal character pair. 


(Continued on next page) 
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Table G-4 (Cont.) 
File Header Label (HDR3) 


Character Length 
Position Field Name (in bytes) Contents 
Byte Pair Byte Pair 
1 4 17 20 
2 3 18 19 
3 2 19 18 
4 1 20 17 
5 8 21 24 
6 7 22 23 
7 6 23 22 
8 5 24 21 
9 12 25 28 
10 11 26 27 
11 10 27 26 
12 9 28 25 
13 16 29 32 
14 15 30 31 
15 14 31 30 
16 13 32 29 
Using the list, the eighth 
hexadecimal character pair is 
the expansion of the fifth 
user file attribute byte, and 
the fourth user file 
attribute byte is expanded 
into the first hexadecimal 
character pair. The 
hexadecimal pair is the 
normal representation of the 
contents of the byte; that 
is, if the byte contains a 
15.05 the hexadecimal 
representation of it is OF. 
69-80 Reserved 10 Spaces. 


G.1.3.1 File Identifier Processing by Files-l1l - The magnetic tape 
ACP processes Files-ll type file identifiers as described below. 
However, if the file name is enclosed in quotes, it is processed as an 
ANSI file name, all “a" characters are legal, all 17 positions may be 
used, and the only conversion that takes place is making all lowercase 
characters into uppercase characters and converting all characters 
that are not "a" characters to question marks. 


At file input, the file identifier is handled as follows: 

1. The first nine characters at a maximum are processed by an 
ASCII to Radix-50 converter. The conversion continues until 
one of the following occurs: 

a. A conversion failure. 


b. Nine characters are converted. 


c. A period (.) is encountered. 
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2. If the period is encountered, the next three characters after 
the period are converted and treated as the file type. Ifa 
failure occurs or all nine characters are converted, the next 
character is examined for a period. If it is a period, it is 
skipped and the next three characters are converted and 
treated as the file type. 


3. The version number is derived from the generation number and 
the generation version number as follows: 


(generation number - 1)*100 + generation version + 1l 


If an invalid version number is computed, it will be changed 
to l. 


At file output, the file identifier is handled as follows: 
1. The file name is placed in the first positions in the file 
identifier field. It can occupy up to nine positions and is 


followed by a period. 


2. The file type of up to three characters is placed after the 
period. The remaining positions are padded with spaces. 


3. The version number is then placed in the generation and 
generation version number fields, as described in the 
following formulas: 


a. Generation number =(vezsig@ # —- 1l\+ 1 
100 


b. Generation version # (version # - 1) Moduto 100 
NOTE 
In both calculations, remainders 


are ignored. 


The following are examples. 


Files-11 Version No. Generation No. Generation Version No. 
1 nl 0 
50 1 49 
100 1 99 
101 2 0 
1010 ll 9 


G.1.4 End-of-Volume Labels 


End-of-volume labels are identical to the file header labels with the 
following exceptions: 


l. Character positions 1 through 3 contain EOV instead of HDR. 


2. The block count field contains the number of records in the 
last file section on the volume. 
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G.1.5 File Trailer Labels 


End-of-file labels (file trailer labels) are identical with file 
header labels, with the following exceptions: 


1. Columns 1 through 3 contain EOF instead of HDR. 


2. The block count contains the number of data blocks in the 
file. 


G.1.6 User File Labels 


User file labels are never written or passed back to you. If present, 
they are skipped. 


G.2 FILE STRUCTURES 


The file structures illustrated below are the types of file and volume 
combinations that the file processor produces. The file processor can 
read and process additional sequences. 


A 


The minimum block size and fixed-length record size is 18 bytes. The 
maximum block size is 8192 bytes. FCS adapts to input files of 
varying block size. 


If HDR2 is not present, the data type is assumed to be fixed (F), and 
the block size and record size are assumed to be the default value for 
the file processor. 512 decimal bytes is the default for both block 
and record size. You can override these block and record sizes with 
the MAG command (see Section G.5), and MOUNT command. The MAG command 
controls block and record size on unlabeled tapes and on ANSI level 1 
and 2 tapes. 


The meaning of the symbols used in the file structure illustrations is 
as follows: 


l. The asterisk (*) indicates a tape mark. As defined by ANSI, 
a tape mark is a special control block recorded on magnetic 
tape to serve as a separator between files and file labels. 

2. BOT indicates beginning of tape. 

3. EOT indicates end of tape. 


4. The comma (,) indicates the physical record delimiter. 


G.2.1 Single File Single Volume 


BOT, VOL1,HDR1,HDR2,HDR3*---DATA-~--*EOF1, EOF 2, EOF3** 


G.2.2 Single File Multivolume 
BOT, VOL1,HDR1, HDR2, HDR3*---DATA---*EOV1,EOV2, EOV3** 


BOT, VOL1,HDR1,HDR2,HDR3*---DATA---*EOF1,EOF2,EOF3** 
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G.2.3 Multifile Single Volume 


BOT, VOL1, HDR1, HDR2, HDR3*~--DATA---*EOF1,EOF2, EOF 3*HDR1,HDR2,HDR3*---DATA 
--*EOF1,EOF2,EOF3** 


G.2.4 Multifile Multivolume 


BOT, VOL1, HDR1, HDR2, HDR3*--DATA--*EOF1,EOF2,EOF3*HDR1,HDR2,HDR3*--DATA--* 
EOV1,EOV2** 


BOT, VOL1,HDR1, HDR2, HDR3*--DATA--*EOF1, EOF 2, EOF3*HDR1, HDR2, HDR3*~~DATA--* 
EOF 1,EOF2,EOF3** 


G.3 END-OF-TAPE HANDLING 


End-of-tape is handled by the magnetic tape file processor. Files are 
continued on the next volume provided that the volume is already 
mounted or mounted upon request. A request for the next volume is 
printed on CO: (console output pseudo device). 


G.4 ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS COMPATIBLE) 


Figure G-l illustrates the format of a file header block that is 
returned by the file header READ ATTRIBUTE command for ANSI magnetic 
tape. The header block is constructed by the magnetic tape primitive 
from data within the tape labels. 
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H.MPOF MAP OFFSET H.IDOF 
FILE SEQUENCE NUMBER H.FNUM 
STRUCTURE LEVEL = 401(8) H.FLEV 


H.FOWN=H.PROG 


UIC (FOR VOLUME) 
PROTECTION CODE (FOR VOLUME) 
RECORD ATTRIBUTES RECORD TYPE CODE 


RECORD SIZE IN BYTES 


N WORDS OF ZERO’S 


FILE NAME RADS50 
FILE TYPE RAD50 


HEADER AREA H.FPRO 


H.UFAT 


X+l.FNAM 
(IDENT OFFSET °2)=xX 


!.FTYP 
X+LFVER 
X+IL.RVNO 
X+t.CRDOT 

IDENTIFICA- 

TION AREA X+1.EXDOT 
X+47. 
X+50. 

COPY OF THE HDR2 LABEL 
(if byte 1 of label = 0, X+130. 
label is not present} 
NULL MAP, 1.E., ZERO’S X+210.= 
P A ‘ : 
MEADOR { (10 BYTES LONG) (MAP OF OFFSET 2) 


ZK-315-81 


Figure G-l1 ANSI Magnetic Tape File Header Block (FCS Compatible) 


G.5 THE MAGNETIC TAPE CONTROL TASK 

The Magnetic Tape Control Task (MAG) allows you to specify file 
attributes for unlabeled tapes, provides positioning functions for 
both unlabeled and ANSI tapes, and allows you to respond to requests 
for new tapes or volumes without mounting a new tape. 


This command can only be used on mounted tapes. The keywords’ are 
valid for both unlabeled and ANSI tapes, unless otherwise noted. 


The format of the MAG command is as follows: 


>MAG SET mmnn:/keyword([/keyword[s]] 


mmnn <: 
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Magnetic tape unit on which the operation is to be performed. 


Keywords: 


/BS=number-of-bytes 


/CC=NONE 
LIST 
FORTRAN 

/EOF 

/EOT 


/EOV 


/INITIALIZE="volume id" 


/POS=number-of-files 


/RS=number-of-characters 


/ REWIND 


Keyword definitions: 


BS 


cc 


/BS=number-of-bytes. Number of characters (bytes) 
per block on amounted tape. You can specify the 
number of characters in either decimal or octal. 
To specify a decimal number, terminate it with a 
period. The default is octal. 


This block size becomes the default for the tape. 
FCS uses this value on output when there is no HDR2 
label present on an ANSI magnetic tape, and when no 
other value was specified on creation of the file. 
FCS reads the file attributes to obtain the _ block 
size when opening an existing file on ANSI magnetic 
tape. ‘ 


The value specified for block size must be greater 
than 14 (decimal) bytes. There is no maximum block 
size. FCS pads a block on ANSI magnetic tape to an 
even length to permit PUTS operations with odd 
fixed-length records. 


/CC=type of carriage control. The default is 
/CC=NONE. 


Valid types of carriage control are as follows: 
NONE 


LIST 
FORTRAN 


EOF 


EOT 


EOV 


INITIALIZE 


POS 
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When reading from an ANSI tape, FCS uses this 
carriage control if: 


@e No HDR2 label is present. 


e The HDR2 label contains a system identification 
other than DEC or OS. 


If a HDR2 label is’ present, FCS uses the 
information in the HDR2 label and ignores the /CC 
keyword. 


This keyword is the only way to specify carriage 
control for unlabeled tapes. 


/EOF. Causes the ACP to return the I/O status code 
IE.EOF to the requesting task. You can use this 
keyword to terminate a request for another tape in 
a volume set. 


This keyword is only valid for ANSI tapes. 


/EOT. Causes the ACP to return the I/O status code 
IE.EOT to the requesting task. You can use this 
keyword to terminate a request for another tape in 
a volume set. 


This keyword is only valid for ANSI tapes. 


/EOV. Causes the ACP to return the I/O status code 
IE.EOV to the requesting task. You can use this 
keyword to terminate a request for another tape in 
a volume set. 


This keyword is only valid for ANSI tapes. 


/INITIALIZE="volume id". The volume label to which 
the tape will be initialized. This keyword allows 
you to create a new volume to satisfy a request 
from the ACP for a new output volume for an ANSI 
tape. The format of the volume identifier is 
identical to the format of the volume identifier 
specified for the MOUNT command. Refer to the 
INITIALIZE command in the RSX-11M/M-PLUS Command 
Language Manual or the RSX-LIM/M-PLUS MCR 
Operations Manual for details. 


This keyword is only valid for ANSI tapes. 


/POS=number-of-files. The number of files (tape 
marks) to be spaced over from the current tape 
position. For example, /POS=0 means access’ the 
current file; /POS=l means space forward one file 
from the current position. The number of files may 
be specified in either decimal or octal. To 
specify a decimal number, terminate the number with 
a period. The default is octal. 


The number of files specified must be between 0 and 
23417 (octal). 
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This keyword is only valid for mounted unlabeled 
tapes. This keyword is not necessary for labeled 
tapes, because files can be accessed by name. 


If a tape containing ANSI or IBM labels is mounted 
as unlabeled, the formula to calculate the position 
of a data file is: 


N= (N-1) *3+1 
where N is the number of the desired file. 


RS /RS=number-of-characters. The number of characters 
per record for fixed-length records on tape. 


Maximum record size is the block size. 


When reading files from an ANSI tape, FCS uses this 
value for record size when no 4HDR2 label is 
present. 


This keyword is the only way to specify record size 
for unlabeled tapes. 


REWIND /REWIND. Specifies that the tape is to be rewound 
to BOT. For ANSI tapes, this keyword rewinds to 
the beginning of the volume set. 


G.5.1 MAG Command Example 


>MOU MMO: /NOLABEL/TR=EBCDIC 
>MAG SET MMO:/BS=80./RS=80./CC=LIST/REWIND 


>! Read the first "file" on the tape to determine the actual tape format 


>PIP TI:=MM0:X 

VOL1X234870 NASHUA 

HDR1DEC2.KP72132 X2348700010001 80256 802860000000IBM OS/VS 370 
HDR2F008000008030DEC2K009 /DEC 2U009 B 60337 


>! This information shows that the tape in fact has labels that 

>! resemble ANSI labels (this tape is in the format of 

>! another computer manufacturer). The actual block size and record size 
>! can be determined from the labels. 

>! Use the MAG SET command to set the actual block and record size. 


>MAG SET MMO0:/BS=800./RS=80. 


>! Use the MAG SET /POS command to position to the next file on the tape. 
>! You could also position to the file by specifying 

>! a position to PIP as follows: PIP TI:=MM0:"POS=R1" 

>! where R indicates REWIND and 1 is the number of tape 

>! marks to space over. 


>MAG SET MMO0:/REWIND/POS=1 


>! Read the data file. Note that PIP requires a dummy file name, even 
>! though the tape is already positioned at the correct file. 


>PIP TI:=MMO: xX 


001 321 03054 MERRIMACK 603 
002 456 03060 NASHUA 603 
003 789 02165 NEWTON 617 
004 124 01845 NORTH ANDOVER 617 
005 345 64801 JOPLIN 714 


G. 5. 


MAG 


MAG 


MAG 


MAG 


MAG 


MAG 


MAG 
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2 MAG Command Error Messages 
-- Device not mounted or mounted foreign 
Explanation: Specified device must be either a mounted ANSI tape 
or a mounted unlabeled tape. A foreign tape that is mounted 
foreign is not known to the magnetic tape ACP and is’ therefore 
the same as an unmounted tape. The MAG command only supports 
mounted tapes. 
User Action: Mount the device with the /NOLABEL qualifier if it 
is an unlabeled tape. Do not use the MAG command with tapes that 
are mounted foreign. 
-- Get command line failure 


Explanation: An illegal indirect command file name was specified 
or MAG could not find the specified indirect command file. 


User Action: Check the specification for the indirect command 
file and reenter the command line. 


-~- Illegal combination of keywords 


Explanation: Keywords were specified that required both an 
unlabeled tape and an ANSI tape. 


User Action: Refer to the keyword descriptions in this chapter 
to determine which switches require ANSI tapes and which require 
unlabeled tapes. 
-- Illegal file attributes combination 


Explanation: A record size was specified that was not less’ than 
or equal to the block size. 


User Action: Specify a record size less than or equal to the 
block size. 


-- Illegal switch value 

Explanation: One of the following: 
e /POS value was greater than 9999. 
e /BS value was less than 14. 

e /RS value was less than 14. 


User Action: Determine which value was illegal and retype the 
command line. 


-- Invalid device or unit 


Explanation: Specified device does not exist or is not a 
magnetic tape. 


User Actions Determine the correct device or unit and retype the 
command line. 


-- Operation is only valid for mounted ANSI tapes 


Explanation: An operation that is only valid for ANSI magnetic 
tape was attempted on an unlabeled tape. 


User Action: Use only valid commands. 
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MAG -- Operation is only valid for unlabeled tapes 


Explanation: An operation that is only valid for unlabeled tapes 
was attempted on an ANSI tape. 


User Action: Use only valid commands. 

MAG -- Privilege violation 
Explanation: On systems with multiuser protection, only the 
terminal to which the tape drive is allocated may change the tape 


characteristics. 


User Action: Reenter the command from the terminal that owns the 
tape drive. 


MAG -- Requested operation inconsistent with tape state 


Explanation: The user specified /EOF, /EOV, or /EOT and the 
magnetic tape ACP rejected it. 


or 
The user specified /INITIALIZE and the ACP rejected it. 


User Action: Determine the state of the tape and type only 
commands that can be performed in the current state. 


MAG -- Syntax error 
Explanations The command was specified incorrectly. 


User Action: Check the correct syntax as described in this 
chapter, and then reenter the command line. 


G.6 UNLABELED TAPE 


A tape that contains no labeling information is called an unlabeled 
tape. An unlabeled tape contains either blocked or _ unblocked 
fixed-length records. When a tape is mounted with the /NOLABEL 
qualifier on the MOUNT command, FCS and RMS can access records on the 
tape using standard read and write operations. This is different from 
mounting a tape foreign (MOU/FOREIGN). When a tape is mounted foreign 
(or not mounted at all on RSX-11M systems), records on the tape must 
be accessed directly using the QIOS operations that are defined for 
the magnetic tape driver. 


G.6.1 Block Size on Tapes Mounted /NOLABEL 
Under certain conditions, if a file is written to a tape, its block 
size will be even and one more than the value specified in the MOUNT 
command. The conditions where this occurs are as follows: 

e The tape is mounted /NOLABEL. 


@ The mount command specifies an odd record size. 


e The mount command specifies an odd block size. 
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FCS adds the padding character, an octal 136 circumflex (%*), to 
odd-sized byte blocks because of a hardware restriction; some tape 
drives will not allow an odd number of bytes to be transferred to or 
from tape. Therefore, blocks of data are padded with the circumflex 
character so that even blocks of data can be written to tape on any 
tape drive. 


G.6.2 Tape Positioning 


Any tape motion before the first read operation must be explicitly 
requested in one of the following ways: 


e The FA.ENB!FA.RWD bit may be set in F.ACTL to request a rewind 
of the volume set prior to create or find-file operations. 


e The MAG SET /POS command may be specified to space forward a 
specified number of files from 0 to 9999. 


@e The MAG SET /REWIND command may be specified to rewind the 
tape to BOT. 


e The file may be referenced by the name "POS=[R][nnnn]" where R 
indicates that the tape is to be rewound, and nnnn is the 
number of files (tape marks) to space forward. For example, 
to read the second file on a tape: 


>PIP TI:=MM:"POS=0001" 


Each tape mark delimits a file. All positioning operations are in 
terms of tape marks. If any type of label is present on the tape, it 
will be treated as a file. 


When a file is deaccessed, position within the file is always 
consistent. 


G.6.3 Specifying File Attributes 


You can specify the attributes for files to be read from tape in three 
ways: 


l. The MOUNT command (see the RSX-11M/M-PLUS MCR Operations 
Manual or the RSX-11M/M-PLUS Command Language Manual). 


2. Any create operation request. You can issue the create 
request from within your program by creating a file and 
closing it without writing any data, or by using the RMS 
DEFINE utility. The FCS Create routine returns the error 
code IE.BTP (bad record type) if an attempt is made to set 
the record type to anything other than fixed length. 


3. The MAG SET command (see Section G.5). 


G.6.4 Tape Translation 


You can request translation for a tape when you mount it with the 
MOUNT command (see the RSX-11M/M-PLUS MCR Operations Manual or the 
RSX-11M/M-PLUS Command Language Manual) Tf you have requested 
translation, your data buffer (the FCS or RMS block buffer) is 
translated within your task. Therefore, on a write operation, the 
data in your task is destroyed. 
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You can add up to three installation-dependent translation routines to 
the magnetic tape ACP by adding routines with the following format: 


USERn:: MOV #TBLPTR,RO nis 1, 25: OF 3% 
RETURN 
TBLPTR: .~.WORD INTRAN 
WORD OUTRAN 
INTRAN: <A 256 byte table for input translation> 
OUTRAN: <A 256 byte table for output translation> 


An example of the EBCDIC translation tables that are provided with 
your system is shown in Section G.6.5. 


You must include these translation routines in the Overlay Description 
Language (ODL) for the magnetic tape ACP when the MTAACP task is 
built. Comments within the files MTABLD.ODL and MTABLD.CMD indicate 
where these routines may be added. 


G.6.5 Example of EBCDIC Translation Tables 


EBCDIC: : MOV #TBLPTR,RO 
RETURN 


; 

TBLPTR: .WORD EBCASC 
-WORD ASCEBC 

; 


-NLIST BEX 


tf 

EBCASC: .BYTE 000,001,002,003,040,011, 040,177,040, 040 
-BYTE 040,013,014,015,016,017,020,021,022,023 
-BYTE 040,040,010, 040, 030, 031,040,040, 040, 035 
-BYTE 040,037,040,040,034,040,040,012,027,033 
-BYTE 040,040,040, 040,040, 005,006, 007,040,040 
-BYTE 026,040,040,036,040,004,040,040,040,040 
-BYTE 024,025,040,032,040,040,040,040, 040,040 
-BYTE 040,040,040,040,133,056,074,050,053,135 
-BYTE 046,040, 040,040, 040,040,040, 040,040,040 
~-BYTE 041,044,052,051,073,136,055,057,040,040 
-BYTE 040,040,040,040,040, 040,174,054, 045,137 
-BYTE 076,077,137,040,040,040,040,040,040, 040 
-BYTE 040,140,072,043,100,047,075,042,040,141 
-BYTE 142,143,144,145,146,147,150,151,040,040 
-BYTE 040,040,040,040,040,152,153,154,155,156 
-BYTE 157,160,161,162,040,040,040,040,040,040 ; 
-BYTE 040,176,163,164,165,166,167,170,171,172 
-BYTE 040,040,040,040,040,040,040,040,040,040 
-BYTE 040,040,040, 040,040,040, 040,040, 040, 040 
-BYTE 040,040,173,101,102,103,104,105,106,107 
-BYTE 110,111,040,040, 040,040, 040,040,175,112 
-BYTE 113,114,115,116,117,120,121,122,040,040 
-BYTE 040,040,040,040,134,040,123,124,125,126 
-BYTE 127,130,131,132,040,040,040,040,040,040 
-BYTE 060,061, 062,063, 064,065,066,067,070,071 
-BYTE 040,040,040,040,040,040 


=e 


=e 


=e 


=e 


’ 
ASCEBC: .BYTE 000,001,002,003,067,055,056,057 
-BYTE 026,005,045,013,014,015,016,017 
-BYTE 020,021,022,023,074,075, 062,046 
-BYTE 030,031,077,047,042,035,065,037 
-BYTE 100,132,177,173,133,154,120,175 ; 40 
-BYTE 115,135,134,116,153,140,113,141 
-BYTE 360, 361, 362, 363, 364, 365, 366, 367 


50. 


100. 


150. 


200. 


250. 
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-BYTE 370,371,172,136,114,176,156,157 


-BYTE 174,301, 302,303, 304, 305, 306, 307 ; 100 
-BYTE 310,311,321, 322,323,324, 325,326 
-BYTE 327,330, 331,342, 343,344,345, 346 
-BYTE 347,350, 351,112,340,117,137,155 
-BYTE 171,201,202, 203, 204, 205, 206, 207 ; 140 
-BYTE 210,211,221,222, 223,224,225, 226 
-BYTE 227,230,231, 242,243,244, 245,246 
-BYTE 247,250,251, 300,152, 320,241,007 
’ 
-BYTE 000,001,002,003,067,055,056,057 
-BYTE 026,005,045,013,014,015,016,017 
-BYTE 020,021,022,023,074,075, 062,046 
-BYTE 030,031,077,047,042,035,065,037 
-BYTE 100,132,177,173,133,154,120,175 ; 200 
-BYTE 115,135,134,116,153,140,113,141 
-BYTE 360,361, 362, 363, 364, 365, 366, 367 
-BYTE 370,371,172,136,114,176,156,157 
-BYTE 174,301, 302,303, 304, 305, 306, 307 ; 240 
-BYTE 310,311,321, 322,323,324,325,326 
-BYTE 327, 330,331,342, 343, 344, 345, 346 
-BYTE 347,350,351,112,340,117,137,155 
-BYTE 171,201,202, 203, 204, 205, 206,207 ; 300 


-BYTE 210,211,221, 222,223,224,225, 226 
-BYTE 227,230, 231,242, 243, 244,245, 246 
-BYTE 247,250,251,300,152,320, 241,007 


EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A TAPE 


»ENABLE QUIET 
-ENABLE SUBSTITUTION 


This command file is invoked with the command 

@MTA outspec=Mx:infile 
and searches a tape mounted unlabeled (which has an ANSI-like structure) 
for the file "infile" and copies it to outspec. 


-; Parse the command line; OUTSPC gets outspec, 
DEV gets Mx, 
INFILE gets the file name to find on tape. 


e 
, 
. 
UU 
. 
td 
e 
e 
e 
e 
e 
, 
. 
e 
° 
f 


-PARSE COMMAN " “ OUTSPC COMMAN 
-PARSE COMMAN "=" OUTSPC INSPEC 
-PARSE INSPEC ":" DEV INFILE 
-IF INFILE EQ "" .GOTO NOTMT 


~-SETS INFILE INFILE+" " 
eSETS INFILE INFILE[1:17. } 

-SETS JUNK DEV[1:1] 

-IF JUNK NE "M" .GOTO NOTMT 


°7 
-; Make a name for the temp file. 


e 
ef 


-TESTFILE TI: 
-PARSE <FILSPC> ":" TMP JUNK 
-SETS TMP TMP+".TMP" 


e 
Lae 


-; Always start at the beginning of the tape. 
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MAG SET 'DEV':/REWIND 


-; Labels have a block and record size of 80. 


MAG SET 'DEV':/BS:80./RS:80. 
~ LOOK: 


° 
er 
; 


Put the labels in a temp file so Indirect can look at them 


PIP 'TMP'='DEV':DUMMY.NAM 
-OPENR ‘TMP’ 

- READLB: 

-READ LABEL 

~IFT <EOF> .GOTO NOSUCH 
-SETS LABELT LABEL [1:3] 


-; Skip any Volume header labels 


-IF LABELT = "VOL" .GOTO READLB 
-IF LABELT NE “HDR" .GOTO ILLFMT 
~SETS LABELT LABEL [4:4] 

-IF LABELT NE "1" .GOTO ILLFMT 
-SETS LABELT LABEL [5:21.] 


ev 


-; If the names do not match, go get the next set of labels. 


-IF LABELT NE INFILE .GOTO TRYNXT 


; 
-; We have found the file, see if there is a HDR2 with size info. 


»~READ LABEL 

-IFT <EOF> .GOTO READFL 

~SETS LABELT LABEL [1:4] : 
-IF LABELT NE "HDR2" .GOTO READFL 


? 
; Yes, we have a HDR2 label. 


~SETS LABELT LABEL [(37.:37.] 
-SETS CC "LI" 

-IF LABELT = "A" .SETS CC "FO" 
~IF LABELT = "M" .SETS CC "NO" 
-SETS BS LABEL [6:10.] 

-SETS RS LABEL[11.:15.] 


er 
-; Set up the block size, record size, and carriage control 
-; based on what was in HDR2. 

MAG SET 'DEV':/BS:'BS'./RS:'RS'./CC:'cc' 

~SETS LABELT LABEL [5:5] 

e-IF LABELT EQ "F" .GOTO READFL 

~-DISABLE QUIET 


!IMTA - Warning, Record Format is 'LABELT'; only F Format is fully supported. 
e-ENABLE QUIET 


- READFL : 
- CLOSE 
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ov 
-; Transfer the file. 

PIP ‘OUTSPC'='DEV':"POS=1" 
-GOTO ENDIT 

~TRYNXT: 

eCLOSE 

MAG SET 'DEV':/POS=3 

~GOTO LOOK 

eILLEMT: 

e~DISABLE QUIET 

-DISABLE MCR 


MTA - Tape is not in a format that I understand. 


-GOTO ENDIT 
-NOTMT : 
-DISABLE QUIET 
»~DISABLE MCR 


MTA - Input file spec must specify a magnetic tape device and a file name. 


EXIT 

-NOSUCH: 
-DISABLE QUIET 
-DISABLE MCR 


MTA - No such file -- ‘INSPEC' 


~ENDIT: 

.ENABLE MCR 
.ENABLE QUIET 

PIP 'TMP';: /DE/NM 
EXIT ~ 
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STATISTICS BLOCK 


The format of the statistics block is shown in Figure H-1l below. The 
statistics block is allocated manually in your program as described in 


Section 3.1.2. 
Word 0 HIGH LOGICAL BLOCK NUMBER 
(0 if file is noncontiguous) 
Word 1 LOW LOGICAL BLOCK NUMBER 
(0 if file is noncontiguous) 
Word 2 
Word 4 
LOCK COUNT ACCESS COUNT 


ZK-304-81 


Figure H-l Statistics Block Format 


APPENDIX I 


ERROR CODES 


This appendix includes the code for: 


me we Me we NS TE NEO 


te we MO Me MO TO Te TO TO TSO TSO TWH Te We NO WS We TSW Te We VO We TS Te me We Te Ws Ne WE 


e I1/0 error codes 
e Directive Status Word error codes 


e I/0 function codes 


- TITLE QIOMAC - QIOSYM MACRO DEFINITION 
DATE OF LAST MODIFICATION: 


John R. Covert 16-Nov-1984 


*xxk* ALWAYS UPDATE THE FOLLOWING TWO LINES TOGETHER 
- IDENT /0375/ 
QI. VER=0375 


COPYRIGHT (C) 1983, 1984 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 


THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 


DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 
PETER H. LIPMAN 1-OCT-73 


+ 


MACRO TO DEFINE STANDARD QUEUE I/0 DIRECTIVE FUNCTION VALUES 
AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL 
DEFINITION) USE: 


QIosy$ ;DEFINE SYMBOLS 


we Me Te Me Ne MO Ne 


~e we MO Me NS NO NO 


me we Ne 


ERROR CODES 


TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE: 
QIOSYS DEFSG 7SYMBOLS DEFINED GLOBALLY 


THE MACRO CAN BE CALLED ONCE ONLY AND THEN 
REDEFINES ITSELF AS NULL. 


-MACRO QIOSYS SSSGBL,SSSMSG 
.IIF IDN,<SSSGBL>,<DEFSG>, .GLOBL QI.VER 


IF IDN, <SSSMSG>,<DEFSS> 

SSSMAX=0 

SSMSG=1 

.IFF 

SSMSG=0 

. ENDC 

-MCALL IOERRS 

IOERRS SSSGBL ;I1/O0 ERROR CODES FROM HANDLERS, FCP, FCS 
.-MCALL DRERRS 

DRERRS SSSGBL ;DIRECTIVE STATUS WORD ERROR CODES 
IF DIF,<SSSMSG>,<DEFSS> 

-MCALL FILIOS 

FILIOS SSSGBL ;DEFINE GENERAL I/O FUNCTION CODES 
-MCALL SPCIOS 

SPCIOS SSSGBL ;DEVICE-DEPENDENT I/O FUNCTION CODES 
. MACRO QIOSYS ARG, ARG1,ARG2 :RECLAIM MACRO STORAGE 
- ENDM QIOosYs 

. ENDC 

. ENDM QIosys 


DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES 
IN THE FIRST WORD OF THE I/O STATUS BLOCK 
THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE 
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FDB) 
THE BYTE F.ERR+1 IS 0 IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE. 


. ENABL LC 

. MACRO IOERRS SSSGBL ~ 
. MCALL . IOER.,DEFINS 

ore IDN, <SSSGBL>, <DEFSG> 
..-GBL=1 

. IFF 

. «.GBL=0 

. ENDC 

.IIF NDF , SSMSG, SSMSG=0 


SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS 


- IOER. IE.BAD,-01.,<Bad parameters> 

- IOER. IE.IFC,-02.,<Invalid function code> 

- IOER. IE.DNR,-03.,<Device not ready> 

- IOER. IE.VER,-04.,<Parity error on device> 
- IOER. IE.ONP,-05.,<Hardware option not present> 
-IOER. IE.SPC,-06.,<Illegal user buffer> 

- IOER. IE.DNA,-07.,<Device not attached> 

- ILOER. IE.DAA,-08.,<Device already attached> 
- IOER. IE.DUN,-09.,<Device not attachable> 

- IOER. IE. EOF,-10.,<End of file detected> 

~ IOER. IE.EOV,-1l1.,<End of volume detected> 


=e me MO 


me me Ne 


ERROR CODES 


-IOER. IE.WLK,-12.,<Write attempted to locked unit> 

~IOER. IE.DAO,-13.,<Data overrun> 

. IOER. IE.SRE,-14.,<Send/receive failure> 

. IOER. IE.ABO,-15.,<Request terminated> 

-IOER. IE.PRI,-16.,<Privilege violation> 

~ IOER. IE.RSU,-17.,<Shareable resource in use> 

-IOER. IE.OVR,-18.,<Illegal overlay request> 

- IOER. IE.BYT,-19.,<Odd byte count (or virtual address) > 

- IOER. IE.BLK,-20.,<Logical block number too large> 

- IOER. IE.MOD,-21.,<Invalid UDC module #> 

- LOER. IE.CON,-22.,<UDC connect error> 

- IOER. IE.BBE,-56.,<Bad block on device> 

- LOER. IE.STK,-58.,<Not enough stack space (FCS or FCP)> 

- IOER. IE.FHE,-59.,<Fatal hardware error on device> 

- IOER. IE.EOT,-62.,<End of tape detected> 

~ IOER. IE.OFL,-65.,<Device off line> 

- IOER. IE.BCC,-66.,<Block check, CRC, or framing error> 

- IOER. IE.NFW,-69.,<Path lost to partner> ;THIS CODE MUST BE ODD. 
~IOER. IE.DIS,-69.,<Path lost to partner> ;DISCONNECTED (SAME AS NFW) 
- IOER. IE.PNT,-71.,<Partition/Region not in system> 

-IOER. IE.NDR,-72.,<No dynamic space available> ; SEE ALSO IE.UPN 
. IOER. IE.TMO,-95.,<Timeout on request> ; see also IS.TMO 
~IOER. IE.CNR,-96.,<Connection rejected> 

- IOER. IE.MII,-99.,<Media inserted incorrectly> 

-IOER. IE.SPI,-100.,<Spindown ignored> 


FILE PRIMITIVE CODES 


« IOER. IE.NOD,-23.,<Caller's nodes exhausted> 

» IOER. IE.DFU,-24.,<Device full> 

» IOER. IE. IFU,-25.,<Index file full> 

» IOER. IE.NSF,-26.,<No such file> 

» IOER. IE.LCK,-27.,<Locked from read/write access> 

» LOER. IE.HFU,-28.,<File header full> 

» IOER. IE.WAC,-29.,<Accessed for write> 

. IOER. IE.CKS,-30.,<File header checksum failure> 

» IOER. IE.WAT,-31.,<Attribute control list format error> 
» IOER. IE.RER,-32.,<File processor device read error> 
- IOER. IE.WER,-33.,<File processor device write error> 
- IOER. IE.ALN,-34.,<File already accessed on LUN> 

- IOER. IE.SNC,-35.,<File ID, file number check> 

- IOER. IE.SQC,-36.,<File ID, sequence number check> 

~ IOER. IE.NLN,-37.,<No file accessed on LUN> 

~ IOER. IE.CLO,-38.,<File was not properly closed> 

~ IOER. IE.DUP,-57.,<ENTER - duplicate entry in directory> 
~IOER. IE.BVR,-63.,<Bad version number> 

~ IOER. IE.BHD,-64.,<Bad file header> 

-IOER. IE.EXP,-75.,<File expiration date not reached> 
- IOER. IE.BTF,-76.,<Bad tape format> 

-IOER. IE.ALC,-84.,<Allocation failure> 

~IOER. IE.ULK,-85.,<Unlock error> 

-IOER. IE.WCK,-86.,<Write check failure> 

~ IOER. IE.DSQ,-90.,<Disk quota exceeded> 


FILE CONTROL SERVICES CODES 


- IOER. IE.NBF,-39.,<OPEN - no buffer space available for file> 
~IOER. IE.RBG,-40.,<Illegal record size> 

-IOER. IE.NBK,-41.,<File exceeds space allocated, no blocks> 

- IOER. IE.ILL,-42.,<Illegal operation on file descriptor block> 


me ue we 


ue we we me me tO me me te 


me Ne Ne 


ERROR CODES 


- IOER. IE.BTP,-43.,<Bad record type> 

~ IOER. IE.RAC,-44.,<Illegal record access bits set> 
~IOER. IE.RAT,-45.,<Illegal record attributes bits set> 
~ IOER. IE.RCN,-46.,<Illegal record number - too large> 
~IOER. IE.2DV,-48.,<Rename - 2 different devices> 

» IOER. IE.FEX,-49.,<Rename - new file name already in use> 
- IOER. IE.BDR,-50.,<Bad directory file> 

-IOER. IE.RNM,-51.,<Can't rename old file system> 

- IOER. IE.BDI,-52.,<Bad directory syntax> 

- IOER. IE.FOP,-53.,<File already open> 

- IOER. IE.BNM,-54.,<Bad file name> 

~IOER. IE.BDV,-55.,<Bad device name> 

. IOER. IE.NFI,-60.,<File ID was not specified> 

- IOER. IE.1ISQ,-61.,<Illegal sequential operation> 
~IOER. IE.NNC,-77.,<Not ANSI 'D' format byte count> 


NETWORK ACP, PSI, AND DECDATAWAY CODES 


- IOER. IE.NNN,-68.,<No such node> 

~IOER. IE.BLB,-70.,<Bad logical buffer> 

- IOER. IE.URJ,-73.,<Connection rejected by user> 
-IOER. IE.NRJ,-74.,<Connection rejected by network> 
- IOER. IE.NDA,-78.,<No data available> 

~ IOER. IE.IQU,-91.,<Inconsistent qualifier usage> 

~ IOER. IE.RES,-92.,<Circuit reset during operation> 
~IOER. IE.TML,-93.,<Too many links to task> 

~ IOER. IE.NNT,-94.,<Not a network task> 

~ IOER. IE.UKN,-97.,<Unknown name> 


ICS/ICR ERROR CODES 
~ IOER. IE.NLK,-79.,<Task not linked to specified ICS/ICR interrupts> 


- 1OER. IE.NST,-80.,<Specified task not installed> 
- IOER. IE.FLN,-81.,<Device offline when offline request was issued> 


TTY ERROR CODES 


-IOER. IE. IES,-82.,<Invalid escape sequence> 
~ IOER. IE.PES,-83.,<Partial escape sequence> 


RECONFIGURATION CODES 


~IOER. IE. ICE,-47.,<Internal consistancy error> 
. LOER. IE.ONL,-67.,<Device online> 
- IOER. IE.SZE,-98.,<Unable to size device> 


PCL ERROR CODES 


- IOER. IE.NTR,-87.,<Task not triggered> 


. IOER. IE.REJ,-88.,<Transfer rejected by receiving CPU> 
-IOER. IE.FLG,-89.,<Event flag already specified> 


=e me S08 


me we NO 


ERROR CODES 


SUCCESSFUL RETURN CODES-~--- 


DEFINS IS.PND,+00. OPERATION PENDING 
DEFINS IS.SuC,+01. ; OPERATION COMPLETE, SUCCESS 
DEFINS IS.RDD,+02. ;FLOPPY DISK SUCCESSFUL COMPLETION 
;OF A READ PHYSICAL, AND DELETED 
;DATA MARK WAS SEEN IN SECTOR HEADER 
DEFINS IS.TNC,+02. ; (PCL) SUCCESSFUL TRANSFER BUT MESSAGE 
;TRUNCATED (RECEIVE BUFFER TOO SMALL). 
DEFINS IS.CHW, +04. ; (IBM COMM) DATA READ WAS RESULT OF 
; IBM HOST CHAINED WRITE OPERATION 
DEFINS IS.BV,+05. ; (A/D READ) AT LEAST ONE BAD VALUE 
*WAS READ (REMAINDER MAY BE GOOD). 
;BAD CHANNEL IS INDICATED BY A 
;NEGATIVE VALUE IN THE BUFFER. 
DEFINS IS.DAO,+02. ;SUCCESSFUL BUT WITH DATA OVERRUN 
7 (NOT TO BE CONFUSED WITH IE.DAO) 
TTY SUCCESS CODES 
DEFINS IS.CR,<15*400+1> ;CARRIAGE RETURN WAS TERMINATOR 
DEFINS IS.ESC,<33*400+1> ;ESCAPE (ALTMODE) WAS TERMINATOR 
DEFINS IS.CC,<3*400+1> 7;CONTROL-C WAS TERMINATOR 
DEFINS IS.ESQ,<233*400+1> ;ESCAPE SEQUENCE WAS TERMINATOR 
DEFINS IS.PES,<200*400+1> ;PARTIAL ESCAPE SEQUENCE WAS TERMINATOR 
DEFINS IS.EOT,<4*400+1> ;EOT WAS TERMINATOR (BLOCK MODE INPUT) 
DEFINS IS.TAB,<11*400+1> ;TAB WAS TERMINATOR (FORMS MODE INPUT) 
DEFINS IS.TMO,+2. ;REQUEST TIMED OUT 
DEFINS IS.00B,+3. ;OUT OF BAND TERMINATOR (TERM IN HIGH BYTE) 
DEFINS IS.TMM,+4. ;READ COMPLETED, MANAGEMENT MODE SEQ RCVD 


me me MO 
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Professional Bisync Success Codes 


DEFINS 
DEFINS 
DEFINS 


IS.RVI,+2. 
IS.CNV,+3. 
IS. XPT, +5. 


7 DATA 
; DATA 
+ DATA 


Professional Bisync Abort Codes 


These codes are returned in the 


when the low byte contains IE.ABO. 


DEFINS 
DEFINS 
DEFINS 
DEFINS 
DEFINS 
DEFINS 
DEFINS 


kkkekkk 


SB.KIL,-l. 
SB.ACK,-2. 
SB.NAK,-3. 
SB.ENQ,-4. 
SB.BOF,-5. 
SB.TMO,-6. 
SB.DIS,-7. 


THE NEXT AVAILABLE ERROR 


kkakkne 


IF 

» MACRO 
. ENDM 
« ENDC 
- ENDM 


EQ, $SMSG 
IOERRS A 
IOERRS$ 


IOERRS 


ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 
ABORTED 


~O Me TO We TWO We WE 


NUMBER IS: 


SUCC. XMITTED; HOST ACKED W/RVI 
SUCC. XMITTED; HOST ACKED W/CONVERSATION 
SUCC. RECVD IN TRANSPARENT MODE 


high byte of the first word of the IOSB 


BY IO.KIL 

BECAUSE TOO MANY ACKS RECD OUT OF SEQ 
BECAUSE NAK THRESHOLD EXCEEDED 
BECAUSE ENQ THRESHOLD EXCEEDED 
BECAUSE OF IO.RLB BUFFER OVERFLOW 
BECAUSE OF TIMEOUT 

BECAUSE HOST DISCONNECTED W/ DLE, EOT 


-101. 


me Ne we M8 we NE Me NO 


~e me we 


ue we Me 


=e me te 


ERROR CODES 


DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD 


FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR 
OF THE FILE DESCRIPTOR BLOCK (FDB). TO DISTINGUISH THEM FROM THE 
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE 
F.ERR+1 IN THE FDB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE. 


»MACRO DRERRS SSSGBL 
.»MCALL .QIOE.,DEFINS 

IF IDN,<SSSGBL>,<DEFSG> 
~--GBL=1 

.IFF 

-..GBL=0 

.ENDC 

-IIF NDF, SSMSG, SSMSG=0 


STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD 


-QIOE. IE.UPN,-01.,<Insufficient dynamic storage> ; SEE ALSO IE.NDR 
-QIOE. IE.INS,-02.,<Specified task not installed> 
-QIOE. IE.PTS,-03.,<Partition too small for task> 


-QIOE. IE.UNS,-04.,<Insufficient dynamic storage for send> 
-QIOE. IE.ULN,-05.,<Un-assigned LUN> 

-QIOE. IE.HWR,-06.,<Device handler not resident> 

-QIOE. IE.ACT,-07.,<Task not active> 

-QIOE. IE.ITS,-08.,<Directive inconsistent with task state> 


-QIOE. IE.FIX,-09.,<Task already fixed/unfixed> 
~QIOE. IE.CKP,-10.,<Issuing task not checkpointable> 


-QIOE. IE.TCH,-1ll.,<Task is checkpointable> 

-QIOE. IE.RBS,-15.,<Receive buffer is too small> 

-QIOE. IE.PRI,-16.,<Privilege violation> 

-QIOE. IE.RSU,-17.,<Resource in use> 

-QIOE. IE.NSW,-18.,<No swap space available> 

-QIOE. IE.ILV,-19.,<Illegal vector specified> 

-QIOE. IE.ITN,-20.,<Invalid table number> 

-QIOE. IE.LNF,-21.,<Logical name not found> 

-QIOE. IE.AST,-80.,<Directive issued/not issued from AST> 
-QIOE. IE.MAP,-81.,<Illegal mapping specified> 

-QIOE. IE.IOP,-83.,<Window has I/O in progress> 

-QIOE. IE.ALG,-84.,<Alignment error> 

-QIOE. IE.WOV,-85.,<Address window allocation overflow> 
-QIOE. IE.NVR,-86.,<Invalid region ID> 

~QIOE. IE.NVW,-87.,<Invalid address window ID> 

-QIOE. IE.ITP,-88.,<Invalid TI parameter> 

-QIOE. IE. IBS,-89.,<Invalid send buffer size ( .GT. 255.)> 
-QIOE. IE.LNL,-90.,<LUN locked in use> 

-QIOE. IE.IUI,-91.,<Invalid UIC> 

-QIOE. IE. IDU,-92.,<Invalid device or unit> 

-QIOE. IE.ITI,-93.,<Invalid time parameters> 

-QIOE. IE.PNS,-94.,<Partition/region not in system> 
-QIOE. IE.IPR,-95.,<Invalid priority ( .GT. 250.)> 
-QIOE. IE. ILU,-96.,<Invalid LUN> 


-QIOE. IE. IEF,-97.,<Invalid event flag ( .GT. 64.)> 
~QIOE. IE.ADP,-98.,<Part of DPB out of user's space> 
-QIOE. IE.SDP,-99.,<DIC or DPB size invalid> 


SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD 


DEFINS IS.CLR,0 7EVENT FLAG WAS CLEAR 
7FROM CLEAR EVENT FLAG DIRECTIVE 


™“e me 


™e we we 
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me me we 


me we we 


~e we me 


DEFINS IS.SET,2 
DEFINS IS.SPD,2 
DEFINS IS.SUP,3 
DEFINS IS.WAT,4 
-IF EQ, SSMSG 
- MACRO DRERRS A 
- ENDM DRERRS$ 

- ENDC 

- ENDM DRERRS$ 


ERROR CODES 


;EVENT FLAG WAS SET 
;FROM SET EVENT FLAG DIRECTIVE 
;TASK WAS SUSPENDED 
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OGICAL NAME SUPERSEDED 
PERATION INITIATED, WAIT FOR COMPLETION 
ROM "VAX-11 RSX" RMS-21 ELEPS$ DIRECTIVE 


DEFINE THE GENERAL I/O FUNCTION CODES - DEVICE INDEPENDENT 


-MACRO FILIO$ S$SSGBL 
.»MCALL ~WORD.,DEFINS 

IF IDN, <SSSGBL>,<DEFSG> 
-IFF 

- +» -GBL=0 

.- ENDC 


GENERAL I/O QUALIFIER BYTE DEFINITIONS 


eWORD. IQ.X,001,000 
-WORD. I1Q.Q,002,000 
»WORD. 1Q.S,004,000 
»WORD. IQ. UMD,004,000 
-WORD. IQ.LCK, 200,000 


EXPRESS QUEUE COMMANDS 


-WORD. I0.KIL,012,000 
-WORD. I0.RDN,022,000 
-WORD. I0.UNL, 042, 000 
~WORD. I0.LTK,050,000 
-WORD. IO.RTK, 060,000 
«WORD. I0.SET,030,000 


GENERAL DEVICE DRIVER CODES 


»WORD. IO.WLB, 000,001 
-WORD. TO.RLB,000,002 
-WORD. I0.LOV,010,002 
-WORD. I0.LD0,110,002 
«WORD. IO.ATT,000,003 
-WORD. I0.DET,000,004 


DIRECTORY PRIMITIVE CODES 


eWORD. IO0.FNA,000,011 
«WORD. IO0.RNA,000,013 
eWORD. IO0.ENA,000,014 


FILE PRIMITIVE CODES 


eWORD. IO0.CLN, 000,007 
-WORD. I0.ULK,000,012 
«WORD. I0.ACR,000,015 
»WORD. IO0.ACW,000,016 


7;NO ERROR RECOVERY 


;QUEUE REQUEST IN EXPRESS QUEUE 


7;SYNONYM FOR IQ.UMD 


;USER MODE DIAGNOSTIC STATUS REQUIRED 


;MODIFY IMPLIED LOCK FUNCTION 


;KILL CURRENT REQUEST 

;1/0 RUNDOWN 

;UNLOAD 1/0 HANDLER TASK 
;LOAD A TASK IMAGE FILE 
;RECORD A TASK IMAGE FILE 
;SET CHARACTERISTICS FUNCTION 


*;WRITE LOGICAL BLOCK 

;READ LOGICAL BLOCK 

;LOAD OVERLAY (DISK DRIVER) 
;LOAD D-SPACE OVERLAY (DISK) 
;ATTACH A DEVICE TO A TASK 
;DETACH A DEVICE FROM A TASK 


;FIND FILE NAME IN DIRECTORY 


;REMOVE FILE NAME FROM DIRECTORY 


7;ENTER FILE NAME IN DIRECTORY 


;CLOSE OUT LUN 
;UNLOCK BLOCK 
;ACCESS FOR READ 
7;ACCESS FOR WRITE 


me we 


~e me tO 


~e te NO 


-WORD. 
eWORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 


-MACRO 
- ENDM 
- ENDM 


I0.ACE,000,017 
I0.DAC, 000,020 
IO. RVB,000,021 
IO0.WVB,000,022 
I0.EXT,000,023 
IO.CRE,000,024 
I0.DEL,000,025 
IO.RAT,000, 026 
IO.WAT,000,027 
IO.APV, 010,030 
I0.APC,000,030 


FILIOS A 
FILIOS 
FILIOS 


ERROR CODES 


;ACCESS FOR EXTEND 
;DE-ACCESS FILE 

;READ VIRITUAL BLOCK 
;WRITE VIRITUAL BLOCK 
yEXTEND FILE 

;CREATE FILE 

;DELETE FILE 

;READ FILE ATTRIBUTES 
;WRITE FILE ATTRIBUTES 
;PRIVILEGED ACP CONTROL 
;ACP CONTROL 


DEFINE THE I/O FUNCTION CODES THAT ARE SPECIFIC TO INDIVIDUAL DEVICES 


-MACRO 
-MCALL 
~IF 
---GBL=1 
- IFF 

- - -GBL=0 
.» ENDC 


SPCIOS$ SS$SGBL 
»WORD. ,DEFINS 


IDN,<SSSGBL>,<DEFS$G> 


I/O FUNCTION CODES FOR SPECIFIC DEVICE-DEPENDENT FUNCTIONS 


-WORD. 
-WORD. 
~WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 


IO.WLV,100,001 
IO.WLS,010,001 
IO.WNS,020,001 
IO.WAL,010,001 
IO.WMS ,020,001 
I0.CCO, 040,001 
IO.WBT,100,001 
IO.WLT,010,001 
IO.WLC,020,001 
IO.WPB, 040,001 
IO0.WDD,140,001 
I0.RSN,140,002 
IO.RLV, 100,002 
I0.RST,001,002 
IO.RAL, 010,002 
I0.RNE,020,002 
IO.RNC, 040,002 
IO.RTM,200,002 
IO.RDB, 200,002 
I0.SCF,200,002 
IO.RHD, 010,002 
IO.RNS,020,002 
IO.CRC, 040, 002 
IO. RPB,040,002 
IO. RDF, 240,002 
IO0.RLC,020,002 
IO.ATA,010,003 
10.GTS,000,005 
I0.R1C,000,005 
IO. INL,000,005 
IO.TRM,010,005 
IO.RWD,000,005 
I0.SPB,020,005 
IO.RPL,020,005 
IO.SPF,040,005 
I0.STC,100,005 


7 (DECTAPE) WRITE LOGICAL REVERSE 

3 (COMM.) WRITE PRECEDED BY SYNC TRAIN 

7 (COMM.) WRITE, NO SYNC TRAIN 

; (TTY) WRITE PASSING ALL CHARACTERS 

7 (TTY) WRITE SUPPRESSIBLE MESSAGE 

; (TTY) WRITE WITH CANCEL CONTROL-O 

7 (TTY) WRITE WITH BREAKTHROUGH 

; (DISK) WRITE LAST TRACK 

7 (DISK) WRITE LOGICAL W/ WRITECHECK 

; (DISK) WRITE PHYSICAL BLOCK 

7 (FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA 
7 (MSCP DISK) READ VOLUME SERIAL NUMBER 

; (MAGTAPE,DECTAPE) READ REVERSE 

; (TTY) READ WITH SPECIAL TERMINATOR 

; (TTY) READ PASSING ALL CHARACTERS 

; (TTY) READ WITHOUT ECHO 

; (TTY) READ —- NO LOWERCASE CONVERT 

7 (TTY) READ WITH TIME-OUT 

; (CARD READER) READ BINARY MODE 

; (DISK) SHADOW COPY FUNCTION 

; (COMM.) READ, STRIP SYNC 

; (COMM.) READ, DON'T STRIP SYNC 

; (COMM.) READ, DON'T CLEAR CRC 

; (DISK) READ PHYSICAL BLOCK 

7 (DISK) READ DISK FORMAT 

; (DISK,MAGTAPE) READ LOGICAL W/ READCHECK 
; (TTY) ATTACH WITH ASTS 

; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS 
; (AFC,AD01,UDC) READ SINGLE CHANNEL 

; (COMM.) INITIALIZATION FUNCTION 

7 (COMM.) TERMINATION FUNCTION 

; (MAGTAPE,DECTAPE) REWIND 

7 (MAGTAPE) SPACE "N" BLOCKS 

; (DISK) REPLACE LOGICAL BLOCK (RESECTOR) 
7 (MAGTAPE) SPACE "N" EOF MARKS 

;SET CHARACTERISTIC 


«WORD. 
«WORD. 
«WORD. 
«WORD. 
«WORD. 
«WORD. 
«WORD. 
»WORD. 
»WORD. 
»WORD. 
«WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
»WORD. 
» WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
»WORD. 
-WORD. 
«WORD. 
«WORD. 
»WORD. 
-WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
«WORD. 
-WORD. 
«WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
-WORD. 


-WORD. 
-WORD. 


-WORD. 


-WORD. 
«WORD. 


«WORD. 
-WORD. 
~WORD. 
-WORD. 


I10.SMD,110,005 
10.SEC,120,005 
10.RWU,140,005 
10.SMO,160,005 
10.HNG, 000,006 
10. HLD, 100, 006 
10. BRK, 200,006 
10. RBC, 000, 006 
10.MOD, 000,006 
10. HDX, 010,006 
10.FDX, 020,006 
10.SYN, 040,006 
10. EOF,000,006 
10. ERS, 020,006 
10.DSE, 040,006 
10.RTC,000, 007 
I0.SAO,000,010 
10.SS0,000,011 
IO. RPR,000,011 
10.MSO, 000,012 
10. RTT,001,012 
10.SLO, 000,013 
I10.MLO,000,014 
IO. LED, 000,024 
10.SDO0,000,025 
10.SDI,000, 026 
10.SCS,000,026 
I10.REL, 000,027 
10.MCS,000,027 
I10.ADS, 000, 030 
10.CCI,000,030 
10.LOD, 000, 030 
10.MDI,000,031 
10.DCI, 000,031 
10. PAD, 000,031 
HT.RPP,010, 000 
10.XMT,000,031 
10.XNA,010,031 
10. INI,000,031 
I0.HIS,000, 032 
10.RCI,000,032 
10. RCV, 000, 032 
10.CLK,000,032 
10.CSR,000, 032 
I10.MDO, 000,033 
10.CTI,000, 033 
10.CON, 000,033 


I0.ORG, 010,033 
I0.ANS,020, 033 


I0.STA,000,033 


I0.DTI,000,034 
I0.DIS,000,034 


I0.MDA,000,034 
I0.DPT, 010,034 
I0.RTI,000,035 
I0.CTL, 000,035 


ERROR CODES 


; (FLOPPY DISK) SET MEDIA DENSITY 

7;SENSE CHARACTERISTIC 

; (MAGTAPE,DECTAPE) REWIND AND UNLOAD 

; (MAGTAPE) MOUNT & SET CHARACTERISTICS 

; (TTY) HANGUP DIAL-UP LINE 

; (TMS) HANGUP BUT LEAVE LINE ON HOLD 

; (PRO/TTY) SEND SHORT OR LONG BREAK 

;READ MULTICHANNELS (BUFFER DEFINES CHANNELS) 
; (COMM.) SETMODE FUNCTION FAMILY 

7 (COMM.) SET UNIT HALF DUPLEX 

; (COMM.) SET UNIT FULL DUPLEX 

7 (COMM.) SPECIFY SYNC CHARACTER 

; (MAGTAPE) WRITE EOF 

+ (MAGTAPE) ERASE TAPE 

; (MAGTAPE) DATA SECURITY ERASE 

7;READ CHANNEL - TIME BASED 

; (UDC) SINGLE CHANNEL ANALOG OUTPUT 

7 (UDC) SINGLE SHOT, SINGLE POINT 

; (TTY) READ WITH PROMPT 

7 (UDC) SINGLE SHOT, MULTI-POINT 

; (TTY) READ WITH TERMINATOR TABLE 

7 (UDC) LATCHING, SINGLE POINT 

; (UDC) LATCHING, MULTI-POINT 

7 (LPS11) WRITE LED DISPLAY LIGHTS 

; (LPS11) WRITE DIGITAL OUTPUT REGISTER 
;(LPS11) READ DIGITAL INPUT REGISTER 

7 (UDC) CONTACT SENSE, SINGLE POINT 

7 (LPS11) WRITE RELAY 

; (UDC) CONTACT SENSE, MULTI-POINT 

; (LPS11) SYNCHRONOUS A/D SAMPLING 

; (UDC) CONTACT INT - CONNECT 

; (LPA11) LOAD MICROCODE 

; (LPS11) SYNCHRONOUS DIGITAL INPUT 

7 (UDC) CONTACT INT - DISCONNECT 

; (PSI) DIRECT CONTROL OF X.29 PAD 

7 (PSI) RESET PAD PARAMETERS SUBFUNCTION 

7 (COMM.) TRANSMIT SPECIFIED BLOCK WITH ACK 
7 (COMM.) TRANSMIT WITHOUT ACK 

; (LPA11) INITIALIZE 

; (LPS11) SYNCHRONOUS HISTOGRAM SAMPLING 

7 (UDC) CONTACT INT - READ 

7 (COMM.) RECEIVE DATA IN BUFFER SPECIFIED 
; (LPA11) START CLOCK 

; (BUS SWITCH) READ CSR REGISTER 

7 (LPS11) SYNCHRONOUS DIGITAL OUTPUT 

7 (UDC) TIMER - CONNECT 

7 (COMM.) CONNECT FUNCTION 

;(VT11) - CONNECT TASK TO DISPLAY PROCESSOR 
; (BUS SWITCH) CONNECT TO SPECIFIED BUS 

; (COMM./PRO) DIAL TELEPHONE AND ORIGINATE 
; (COMM.) INITIATE CONNECTION IN ORIGINATE MODE 
7 (COMM.) INITIATE CONNECTION IN ANSWER MODE 
; (LPA11) START DATA TRANSFER 

; (XJDRV) - SHOW STATE 

; (UDC) TIMER - DISCONNECT 

7 (COMM.) DISCONNECT FUNCTION 

;(VT11) - DISCONNECT TASK FROM DISPLAY PROCESSOR 
; (BUS SWITCH) SWITCHED BUS DISCONNECT 

; (LPS11) SYNCHRONOUS D/A OUTPUT 

; (BUS SWITCH) DISCONNECT TO SPECIF PORT NO. 
; (UDC) TIMER - READ 

; (COMM.) NETWORK CONTROL FUNCTION 


ue me NO 


me we NO Ne Ne 


me ume NO 


me te Me 


me te te 


-WORD. IO0.STP,000,035 


-WORD. IO0.SWI,000,035 
~WORD. IO.CNT,000,036 


.-WORD. IO. ITI,000, 036 
EXTENDED I/O FUNCTION 


-WORD. I0.EIO,000, 037 


ERROR CODES 


; (LPS11,LPA11) STOP IN PROGRESS FUNCTION 
; (VT11) - STOP DISPLAY PROCESSOR 

; (BUS SWITCH) SWITCH BUSSES 

;(VT11) - CONTINUE DISPLAY PROCESSOR 

7 (XJDRV) - SHOW COUNTERS 

7 (UDC) TIMER - INITIALIZE 


; (TTY) TSA EXTENDED I/0 


PRO 300 SERIES BITMAP FUNCTIONS 


NOTE: THESE FUNCTIONS ARE FOR DEC USE ONLY AND ARE SUBJECT TO CHANGE 


-WORD. IO.RSD, 030,014 
.WORD. I10.WSD,010,013 
DEFINS  SD.TXT,O 
DEFINS  SD.GDS,1 


READ SPECIAL DATA 
WRITE SPECIAL DATA 
TEXT DATA TYPE FOR SPECIAL DATA 
GIDIS DATA TYPE FOR SPECIAL DATA 


me Me Ne TS 


PROFESSIONAL 300 BISYNC DRIVER (XJDRV) FUNCTIONS 


-WORD. SB.PRT,020, 003 
-WORD. SB.CLR,010,036 
-WORD. SB.RDY, 010,033 
-WORD. SB.NRD,020,033 
-WORD. I0.LBK, 000,035 


-WORD. SB.CBL,010,035 
-WORD. SB.CLK,020,035 


COMMUNICATIONS FUNCTIONS 


-WORD. I0.CPR,010, 033 


~WORD. I0.CAS,020,033 
-WORD. I0.CRJ, 040,033 
-WORD. I0.CBO,110,033 
-WORD. IO0.CTR,210,033 
»~WORD. IO.GNI,010,035 


-WORD. IO.GLI,020,035 
~WORD. I0.GLC,030,035 
-WORD. 10.GRI,040,035 
-WORD. IO0.GRC,050,035 
-WORD. I0.GRN, 060,035 
-WORD. I0.CSM,070,035 
-WORD. I0.CIN,100,035 
-WORD. IO0.SPW,110,035 
-WORD. IO.CPW,120,035 
~WORD. IO.NLB,130,035 
-WORD. IO.DLB, 140,035 


ICS/ICR I/O FUNCTIONS 


-WORD. IO0.CTY,000,007 
~WORD. IO0.DTY,000,015 
-WORD. IO.LDI,000,016 
-WORD. I0.UDI,010,023 
-WORD. IO.LTI,000,017 
-WORD. I0.UTI,020,023 


ATTACH AS A PRINTER 

CLEAR COUNTERS (IO.CNT SUBFUNCTION) 

SET DEVICE STATE READY (I0.STA SUBFUNC) 
SET DEVICE STATE NOT READY 


me WH me NO 


PERFORM LOOPBACK TEST 


=e 


PERFORM CABLE LOOPBACK TEST 
DEVICE PERFORMS LINE CLOCKING 


we ome 


7;CONNECT NO TIME-OUTS 
7;CONNECT WITH AST 

;CONNECT REJECT 

;BOOT CONNECT 

7; TRANSPARENT CONNECT 

7;GET NODE INFORMATION 

7;GET LINK INFORMATION 

7;GET LINK INFO CLEAR COUNTERS 
;GET REMOTE NODE INFORMATION 
7;GET REMOTE NODE ERROR COUNTS 
;GET REMOTE NODE NAME 

;CHANGE SOLO MODE 

;CHANGE CONNECTION INHIBIT 
;SPECIFY NETWORK PASSWORD 
;CHECK NETWORK PASSWORD 

7NSP LOOPBACK 

7;DDCMP LOOPBACK 


*CONNECT TO TERMINAL INTERRUPTS 
;DISCONNECT FROM TERMINAL INTERRUPTS 
*LINK TO DIGITAL INTERRUPTS 

;UNLINK FROM DIGITAL INTERRUPTS 

*;LINK TO COUNTER MODULE INTERRUPTS 
7UNLINK FROM COUNTER MODULE INTERRUPTS 


me we NS 


me te TO 


mo me MO we 


=e se Se 


=e se SO 


~WORD. 
-WORD. 
~WORD. 
-WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 


IPll 


-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
-WORD. 
- WORD. 
«WORD. 
-WORD. 


IO.LTY, 000,020 
I0.UTY,030,023 
I0.LKE, 000,024 
I10.UER, 040,023 
IO.NLK, 000,023 
IO.ONL,000,037 
I0.FLN,000,025 
I0.RAD,000,021 


I/O FUNCTIONS 


IO.MAO,010,007 
I0.LEI,010,017 
IO0.RDD, 010,020 
I0.RMT,020,020 
I0.LSI,000, 022 
I0.UEI,050,023 
I0.USI, 060,023 
I0.CSI,000,026 
I0.DSI,000,027 
I0. RAM, 000,032 
IO0.RLK, 000,013 
I0.EBT,000,011 


PCL11 I/0 FUNCTIONS 


~WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 


- MACRO 
- ENDM 
- ENDM 


DEFINE THE I/0 CODES FOR USER-MODE DIAGNOSTICS. 


IO.ATX,000,001 
10.ATF,000,002 
I0.CRX, 000,031 
I10.DRX,000,032 
IO.RTF,000, 033 


SPCIOS A 
SPCIOS 
SPCIOS 


ERROR CODES 


;LINK TO REMOTE TERMINAL INTERRUPTS 
;UNLINK FROM REMOTE TERMINAL INTERRUPTS 
7;LINK TO ERROR INTERRUPTS 

;UNLINK FROM ERROR INTERRUPTS 

7;UNLINK FROM ALL INTERRUPTS 

;UNIT ONLINE 

;UNIT OFFLINE 

;READ ACTIVATING DATA 


*MULTIPLE ANALOG OUTPUTS 

;LINK EVENT FLAGS TO INTERRUPT 
*READ DIGITAL DATA 

;READ MAPPING TABLE 

;LINK TO DSI INTERRUPTS 
;UNLINK EVENT FLAGS 

;UNLINK FROM DSI INTERRUPTS 
;CONNECT TO DSI INTERRUPTS 
*;DISCONNECT FROM DSI INTERRUPTS 
;READ ANALOG MAPPING TABLES 
7;READ RESOURCE LINKAGES 

;CHECK EBIT STATUS 


;ATTEMPT TRANSMISSION 
;ACCEPT TRANSFER 

7;CONNECT FOR RECEPTION 
;DISCONNECT FROM RECEPTION 
;REJECT TRANSFER 


ALL DIAGNOSTIC 


FUNCTIONS ARE IMPLEMENTED AS A SUBFUNCTION OF I/0 CODE 10 (OCTAL). 


-MACRO 
-MCALL 


-IF IDN 


.-GBL=1 

- IFF 
. -GBL=0 

- ENDC 


UMDIOS 
»WORD.,DEFINS 


SS$$GBL 


<SSSGBL>,<DEFSG> 


DEFINE THE GENERAL USER-MODE 1/0 QUALIFIER BIT. 


-WORD. 


IQ.UMD,004,000 


;USER-MODE DIAGNOSTIC REQUEST 


DEFINE USER-MODE DIAGNOSTIC FUNCTIONS. 


-WORD. 
-WORD. 
-WORD. 


I0.HMS,000,010 
I0.BLS,010,010 
I0.OFF,020,010 


; (DISK) HOME SEEK OR RECALIBRATE 
; (DISK) BLOCK SEEK 
; (DISK) OFFSET POSITION 


me me te SOS NO me ws TNO 


me me =O SO NO 


me we ~wO 


-WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 


I0.RDH, 030,010 
I0.WDH, 040,010 
IO0.WCK, 050,010 
IO. RNF,060,010 
IO.RNR,070,010 
IO0.LPC,100,010 
IO.RTD,120,010 
IO0.WTD, 130,010 
IO0.TDD, 140,010 
I0.DGN,150,010 
IO.WPD, 160,010 
IO0.RPD,170,010 
IO.CER,200,010 
I0.CEW, 210,010 


MACRO REDEFINITION TO NULL 


«MACRO 
- ENDM 


- ENDM 


HANDLER ERROR CODES RETURNED IN I/O STATUS BLOCK ARE DEFINED THROUGH THIS 


UMDIO$ A 


UMDIOS 


ERROR CODES 


; (DISK) READ DISK HEADER 

; (DISK) WRITE DISK HEADER 

; (DISK) WRITECHECK (NONTRANSFER) 

; (DECTAPE) READ BLOCK NUMBER FORWARD 

; (DECTAPE) READ BLOCK NUMBER REVERSE 

; (MAGTAPE) READ LONGITUDINAL PARITY CHAR 
7 (DISK) READ TRACK DESCRIPTOR 

; (DISK) WRITE TRACK DESCRIPTOR 

7 (DISK) WRITE TRACK DESCRIPTOR DISPLACED 
;DIAGNOSE MICRO PROCESSOR FIRMWARE 


; (DISK) WRITE PHYSICAL BLOCK 
; (DISK) READ PHYSICAL BLOCK 
7 (BISK) READ CE BLOCK 


; (DISK) WRITE CE BLOCK 


MACRO, WHICH THEN CONDITIONALLY INVOKES THE MESSAGE-GENERATING MACRO 
FOR THE QIOSYM.MSG FILE 


-MACRO 
DEFINS 
IF 
-MCALL 
- IOMG. 
. ENDC 
- ENDM 


- IOER. 
SYM,LO 
GT, $SMSG 
- IOMG. 
SYM ,LO,<MSG> 


- IOER. 


SYM,LO,MSG 


I/O ERROR CODES ARE DEFINED THROUGH THIS MACRO, WHICH THEN INVOKES THE 


ERROR MESSAGE-GENERATING MACRO; 


ERROR CODES -129 THROUGH -256 


ARE USED IN THE QIOSYM.MSG FILE 


eMACRO 
DEFINS 
IF 
»MCALL 
- IOMG. 
- ENDC 
- ENDM 


CONDITIONALLY 


»MACRO 
«WORD 
- ENABL 
~ASCIZ 
- DSABL 
» EVEN 
-IIF 

-ENDM 


-QIOE. 
SYM,LO 
GT,$SMSG 
- IOMG. 


SYM,LO,MSG 


SYM, <LO-128.>,<MSG> 


-QIOE. 


GENERATE DATA FOR WRITING A MESSAGE FILE 


- IOMG. 


SYM,LO,MSG 


LT, “O<$SSMAX+<LO>>, SSSMAX2-“O<LO> 


- IOMG. 


me me me 


ERROR CODES 


DEFINE THE SYMBOL SYM WHERE LO IS THE LOW-ORDER BYTE, HI IS THE HIGH BYTE 


-MACRO -WORD. SYM,LO,HI 
DEFINS SYM, <HI*400+L0> 
- ENDM «WORD. = 


.- DSABL LC 


Definitions 
S.BFHD 
S.FATT 


S.FDB 


S.FNAM 


S.FNB 


S.FNBW 


S.FNTY 


S.FSR2 


S.FTYP 


S.NFEN 


APPENDIX J 


FIELD SIZE SYMBOLS 


for these symbols are contained in the System Library. 

- Size of FSR block buffer header in bytes 

- Size of FDB file attribute area in bytes 

- Size of FDB in bytes (including name block) 

- Size of file name in bytes (stored in Radix-50) 

- Size of filename block in bytes 

- Size of filename block in words 

- Size of file name and file type in words (stored in 
Radix-50) 

- Size of FSR2 (basic impure area) 

- Size of file type in bytes (in Radix-50) 

- Size of a complete file name in bytes -- file ID, name, 


type, 


and version 


APPENDIX K 


RSX-11M/M-PLUS FCS LIBRARY SYSGEN OPTIONS 


K.1 FCS LIBRARY OPTIONS 


The system manager has the option of selecting one of several FCS 
libraries as the default FCS library. You can replace the default 
library in SYSLIB with one of the other libraries shown in Table K-1 
by using the /RP switch to the LBR utility. Refer to the 
RSX-11M/M-PLUS Utilities Manual for more information. Table K-1 
contains the FCS libraries that are available with each RSX-11M, 
RSX-1IM-PLUS, and Micro/RSX system, and a brief description of each. 


Table K-1l 
FCS Library Descriptions 


FCS Library Support Description 


{1,1]FCS.OBJ Standard FCS routines. Distributed and 
included in SYSLIB.OLB as the default FCS 
library routines for RSX-11M. 


{[1,1]FCSMTA.OBJ Includes standard FCS routines, plus ANSI 
Magnetic tape support and "big buffering" 
(see Section 2.2.1.6 for block buffer size 
override specification). Distributed and 
included as the default FCS library 
routines for RSX-11M-PLUS and Micro/RSX. 


{[1,1]FCSMBF.OBJ Provides multiple buffering support, big 
buffering support, and ANSI magnetic tape 


support in addition to the standard FCS 
routines. 


K.2 .FCTYP 


The FCS routine .FCTYP returns a description of the FCS conditional 
assembly parameters that were set when FCS was built. 


The format of the call is: 
CALL ~FCTYP 
There are no input parameters. 
The information is returned in Rl. The bits set in the mask word 


returned in Rl correspond to the conditional assembly parameters as 
shown in Table K-2. 


RSX-11M/M-PLUS FCS LIBRARY SYSGEN OPTIONS 


Table K-2 
eFCTYP Values 


Conditional 
Assembly Symbol Rl Bit Mask Symbol Meaning 
RSSANI FT.ANI ANSI magnetic tape support 
RSSBBF FT.BBF . . Big buffer support 
RSSMBF FT.MBF Multibuffer support 


INDEX 


Access 
shared, 2-15 
read, 1-13 
write, 1-12 
Action routine, 7-5 
calling, 7-6 
using, 7-6 
ALUNS directive summary, C-1l 
ANSI tape standard, G-1l 
Append 
file open, 2-15 
-ASCPP routine, convert UIC to. 
binary, 4-7 
-ASLUN routine, assign LUN, 4-10, 
4-15 
ASSIGN command 
in logical name translation, 
4-8 
AST service routine, 2-45, 2-46 


Bad block file header, E-2 
Binary to ASCII conversion 
UIC, 4-7 
Bit map 
index file, E-2 
Blank 
ignoring in command line, 7-8 
Block 
access 
initialization, 2-12 
READS macro, 2-12 
WRITES macro, 2-12 
boundary, 2-6 
buffer 
initialize FDB, 2-18 
pool space, FSR, 2-39 
locking, 2-17, 2-46 
enable, 2-16 
logical, 5-2 
size 
block I/0, 2-12 
reset, CLOSES macro, 2-19 
statistics 
address, 3-11 
tape 
override size, 2-18 
unlocking, 2-47 
virtual, 5-2 
Block boundary 
crossing, record attribute, 3-9 
fixed-length record 
PUTS macro, 3-27 
FSR block buffer, 3-26 
variable-length record 
PUTS macro, 3-27 
Block I/0, 2-10 
block size, 2-12 
buffer, 2-12 
completion event flag, 2-13 
I/O status block, 2-13 


Block I/O (Cont.) 
operation, 1-7 
operation, FD.RWM parameter, 
3-6 
request, record attribute, 3-9 
Block size 
override, 3-10 
Bootstrap block, E-1l 
Buffer 
FSR block 
locate mode, 3-21 
space allocation, 2-20 
multiple, 2-19 
count, 3-10 
type, 2-19 
pool space, FSR, 2-39 
specifying number, 2-20 
task record, 3-21 
locate mode, 3-27 
PUTS macro, 3-26 
Buffer boundary, locate mode, 
3-22 
Buffer count 
default, 2-20 
multiple, 2-19 
Buffer descriptor, task, 3-10 
Buffer flush routine, 4-28 
Buffering 
big, 1-11 
multiple 
performance, 1-10 
record I/0, 1-10 


Carriage control, 2-6, 2-7 
Carriage-control 

record attribute, 3-8 

word, record attribute, 3-9 
CCMLS$ macro, 6-12 
Checkpoint file header, E-2 
Checksum value, 5-4 
CLOSES example, 5-9 
CLOSES macro, 3-1 

block size reset, 2-19 

file processing, 3-18 

file processing completion, 2-8 

format, file processing, 3-18 
COBOL carriage control, 2-6 
Coding TPARS, 7-1 
Command file 

close, 6-12 

reset scan macro, 6-12 
Command line 

ignoring blanks and tabs, 7-8 

parsing, 7-1 

processing, 6-1 
Command String Interpreter 

See CSI 
Control task 

tape, G-1ll 


Index-1l 


INDEX 


Conversion 
UIC, ASCII/binary, 4-6, 4-7 
Convert UIC 
binary to ASCII, 4-7 
CSI, 6-1 
control block bit values 
definition, 6-14 
control block offsets 
definition, 6-14 
expand file specification, 6-19 
initialize control block, 6-19 
parse file specification, 6-19 
routine, 6-14 
run time macros, 6-19 
CSI macro, switch definition, 
6-23 
CSIS macro, 6-14, 6-15 
CSI$1 macro, command syntax 
analyzer, 6-19 
CSI$2 macro 
command semantic parser, 6-20 
initialize control block, 6-19 
parse file specification, 6-19 
CSIS4 macro 
command semantic parser, 6-22 
expand file specification, 6-19 
CSISND macro, 6-24 
define end of descriptor table, 
6-31 
CSISSV macro, 6-23 
create switch value descriptor 
table entry, 6-28 
CSISSW macro, 6-23 
create switch descriptor table 
entry, 6-24 
-CTRL routine, control device, 
4-27 
-CTRL routine, tape, 5-7 


Data format 
ANSI tape, 1-7 
file device, 1-6 
Dataset descriptor, 2-28 
address, initialization, 2-14 
as data structure, 1-4 
definition, 1-3 
general description, 1-5 
OFNBSx macro, 3-15 
pointer 
definition, 1-3 
file-open, 2-14 
initialization, 2-14 
specifying, 2-28 
SDEBUG, 7-2 
Debug routine, 7-6 
DECtape file structure, 5-1 
Default Filename Block 
See DFNB 
DELETS macro, 3-l, 
format 
file operations, 3-39 
Device control routine, 4-27 
Device information 
-PRSDV routine, 4-15 


3-39 


Device name field, 2-34 
Device name string descriptor, 
2-29 
DFNB, 2-31, 3-15 
as data structure, 1-4 
definition, 1-2 
FNBLKS$ macro, 2-31 
OFNBSx macro, 3-15 
specifying, 2-28 
Directive summary 
I/O related, C-1 
Directory 
file, 5-2 
identification information 
-PARSE routine, 4-12 
~PRSDI routine, 4-15 
structure, 5-3 
Directory entry 
delete 
-REMOV routine, 4-19 
insert 
ENTER routine, 4-18 
locate 
-FIND routine, 4-16 
routine, 4-16 
Directory string 
default 
read, 4-2 
write, 4-3 
descriptor, 2-29 
routine 
default, 4-2 
Disk file structure, 5-l 
-DLFNB routine, delete file by 
filename block, 4-26 


End-of-file 

label (tape), G-9 

READS macro, 3-33 
End-of-tape handling, G-10 
End-of-volume label (tape), G-8 
-ENTER routine, insert directory 

entry, 4-18 

Error code 

block locking, 2-48 

file operations, I-1l 

shared file, 2-48 
Error return 

GCMLDS$ macro, 6-5 

IE.IFC, 2-49 

IE.LCK, 2-49 

IE.ULK, 2-49 

IE.WAC, 2-48 
Error routine 

file macro, 3-2 
Event flag 

I/O coordination, 2-43 

I/O synchronization, 3-10 
-EXPLG module 

logical name expansion, 4-14 
Extension 

default, 2-20 
-EXTND routine, extend file, 4-24 


Index-2 


INDEX 


number of retrieval 
A-9 

number of blocks 
for extend, A-7 
block buffer size, 


F.ACTL field, 
pointers, 

F.ALOC field, 
allocated 

F.BBFS field, 
A-8 

F.BDB field, block buffer 
descriptor block address, A-9 

F.BGBC field, big-buffer block 
count, A-8 

F.BKDN field, AST service routine 
address, A-6 

F.BKDS field, block I/0 buffer 
descriptor, A-6 

F.BKEF field, block I/0 event 
flag, A-7 

F.BKPl field, FCS internal 
control bits, A-8 

F.BKST field, I/O status block 
address, A-6 

F.BKVD field, user virtual block 
number, A-8 

F.CHR field, volume 
characteristics byte, A-9 

F.CNTG field, number of blocks to 
be allocated, A-6 

F.DFNB field, default filename 
block pointer, A-7 

F.DSPT field, dataset descriptor 
pointer, A-7 

F.EFBK field, end-of-file block 
number, A-4 

F.EFN field, record I/O event 


flag, A-7 

F.EOBB field, end-of-block buffer, 
A-6 

F.ERR field, error return code 
byte, A-8 

F.ERR1 field, F.ERR extension, 
A-8 

F.EXT field, FDB extension 
address, A-9 

F.FACC field, file access byte, 
A-7 


F.FFBK field, first free byte in 
last block, A-4 

F.FLG field, flag byte, A-9 

F.FNB field, filename block 
offset, A-9 

F.HIBK field, highest allocated 
virtual block number, A-4 

F.LUN field 

FDB, 4-16 

F.LUN field, LUN for FDB, A-7 

F.MBCl field, number of buffers 
in use, A-8 

F.MBCT field, number of multiple 


buffers, A-8 
F.MBFG field, multibuffer flag 
word, A-8 


F.NRBD field, next record buffer 
descriptor, A-6 

F.NREC field, adress of next 
record in block, A-6 


F.OVBS field, override block 
buffer size, A-6 

F.RACC field, record access byte, 
A-4 

F.RATT field, 
byte, A-4 

F.RCNM field, random access 
record number, A-6 

F.RCTL field, device 
characteristics byte, A-5 

F.RCTL, device characteristic 
byte 

-PARSE routine, 4-12 
F.RSIZ field, reocrd-size word, 


record attribute 


A-4 

F.RTYP field, record-type byte, 
A-3 

F.SEQN field, sequence number, 
A-9 

F.STBK field, statistics block 
address, A-6 


F.URBD field, user record buffer 
descriptor, A-6 
F.VBN field, virtual block number, 


A-8 

F.VBSZ field, device buffer size 
word, A-8 

F.VBSZ, device buffer size word 


-PARSE routine, 4-12 
FA.DLK value, not lock file, 
FA.EXL value, block locking, 
FA.LKL value, block locking, 
FA.NSP value, open file no 
supersede, 3-17 

FA.POS value, file position on 
close, 2-16 

FA.RWD value, rewind on close or 
open, 2-16 

FA.SHR value, open file shared 
access, 3-17 

FA.TMP value, open temporary file, 
3-17 

FCS, l-1l 

data structure 

general, 1-4 

file access method, 

I/O macro, 2-1 

important characteristic, 

impure area, 2-38 

library options, K-1 

macro 

FDB information, 
-MCALL directive, 

term definition, 1-2 

with Task Builder, 1-1 
FCS.OBJ FCS library, K-1l 
FCSMBF.OBJ FCS library, K-1 
FCSMTA.OBJ FCS library, K-1 
FCSRES routines, 1-20 
-FCTYP routine, assembly 

parameters, K-1 
FD.BLK parameter 

record attribute, 2-6 

block boundary crossing, 


2-16 
2-17 
2-17 


1-6 


1-3 


2-2 
2-2 


3-9 


Index-3 


INDEX 


FD.CR parameter 
record attribute, 2-6 
line-feed character, 3-8 
FD.FTN parameter, 3-8 
FD.INS parameter 
sequential file, 2-10 
sequential mode, 3-6, 3-9 
FD.PLC parameter 
locate mode, 2-10, 3-6, 3-9 
move mode, 2-10 
FD.PRN parameter 
record attribute, 2-6 
carriage-control word, 3-9 
FD.RAH parameter, read-ahead 
operation, 3-11 
FD.RAH value, read-ahead, 2-19 
FD.RAN parameter 
random access, 2-10, 3-9 
random record I/0, 3-6 
FD.RTN, record attribute, 2-6 
FD.RWM parameter 
block I/O operation, 3-6 
record access, 2-10 
record attribute 
process with block I/0, 3-9 
FD.WBH parameter, write-behind 
operation, 3-11 
FD.WBH value, write behind, 2-19 
FDATSA macro, 2-5 
FDATSR macro, 2-21 
FDB, 2-3 
address, run-time macro, 2-24 
allocate file block, 2-8 
as data structure, 1-4 
block I/0, 2-10 
block locking, 2-17 
block size reset, 2-19 
carriage control, 2-7 
definition, 1-2 
description, 1-5 
extension, logical name 
translation, 4-14 
F.LUN field, 4-16 
F.xxxx field, A-3 
file identification, 3-10 
GETS macro, 3-21 
initial values, 2-1 
initialization, 2-3 
initialize block access, 2-21 
initialize block buffer, 2-18, 


2-22 

initialize block buffer size, 
2-18 

initialize file attribute, 2-5, 
2-21 

initialize file-open section, 
2-14, 2-22 

initialize record access, 2-10, 
2-21 


largest record size, 2-8 
lun specification, 3-10 
macro 
global symbol, 2-26 
local symbol, 2-27 


FDB 
macro (Cont.) 
run-time exceptions, 2-22 
run-time initialization, 2-21 
multiple buffering, 2-19 
type, 2-19 
offset, global/local, 2-25 
OPENSx macro requirement, 3-7 
PUTS macro operation, 3-25 
record I/0, 2-10 
record size, 3-9 
sequence number field, 2-7 
space allocation, 2-5 
WRITES macro, 3-36 
FDBDFS macro, FDB space 
allocation, 2-5 
FDBFSA macro, 2-18 
example, 2-21 
FDBFSR macro, 2-22 
FDBKSA macro 
block access initialization, 
2-12 
example, 2-13 
record access, block I/0, 2-12 
FDBKSR macro, initialize block 
access, 2-21 
FDOPSA macro, 2-14 
example, 2-17 
FDOPSR macro, initialize 
file-open section, 2-22 
FDRCSA macro, 2-10 
example, 2-10 
FDRCSR macro, initialize record 
access, 2-21 
Field size symbols, file 
operation, J-1l 
File 
access 
method, FCS, 1-6 
optimizing, 2-34 
close current command, 6-12 
close indirect command, 6-12 
closing, 3-18 
closing temporary, 3-12 
creating 
FO.WRT value, 3-17 
creating temporary, 3-12 
mark for deletion, 3-13 
delete routine, 4-25, 4-26 
deleting, 3-39 
deleting routine, 4-25 
device 
data format, 1-6 
directory, 5-2 
extend, routine, 4-24 
extending 
WRITES macro, 3-36 
index, 5-2, E-l 
locked, 2-16 
mark for delete, 3-13 
multiple, operation, 5-6 
no lock on close, 2-16 
open by filename block, 3-14 
open by ID, 3-13 


Index-4 


_ INDEX 


File (Cont.) 
open for append 
FO.APD value, 3-17 
open for modify, 3-17 
open for read, 3-17 
open for shared access 
FA.SHR value, 3-17 
open for update and extend, 
3-17 
open for write 
FO.WRT value, 3-17 
open on LP: for printing, 8-2 
open processing, 3-3 
open temporary 
FA.TMP value, 3-17 
opening temporary, 3-12 
mark for deletion, 3-13 
position on close, 2-16 
record access intialization, 
2-21 
rename, 4-23 
sequenced, 2-6 
reading, 2-7 
writing, 2-7 
shared access, 1-12 
single, operation, 5-6 
truncate routine, 4-25 
truncation, 2-11 
File attribute 
initialize, 2-5 
run-time, 2-21 
specifying tape, G-17 
File block 
access initialization, 2-12 
run time, 2-21 
allocation, 2-8 
buffer initialization, 2-18 
run time, 2-22 
locking, 2-17 
File characteristic 
system-controlled 
SC.BAD, bad data block, F-4 
SC.MDL, file marked for 
delete, F-4 
user-controlled 
UC.CON, contiguous file, F-4 
UC.DLK, file improperly 
closed, F-4 
File control routine, 4-1 
File Control Services 
See FCS 
File Descriptor Block 
See FDB 
File extension 
default, 2-20 
default size, 2-9 
size, 2-8 
virtual block, 2-9 
File header block, 5-3, E-2 
format, F-l 
H.XXXX field, F-1l 
header area 
file characteristics, F-4 
file owner information, F-3 


File header block 
header area (Cont.) 
file protection code, F-4 
‘identification area, F-4 
creation date, F-5 
creation time, F-5 
expiration date, F-5 
file version number, F-4 
filename, F-4 
filetype, F-4 
revision date, F-4 
revision number, F-4 
revision time, F-5 
map area, F-5 
tape, G-10 
user file, E-2 
File header block, H.XXXX field, 
F-2 
File header block, I.XXXX field, 
F-2 
File header block, M.XXXX field, 
F-2, F-3 
File header label 
ANSI, 5-4 
tape, G-3 
HDR1, G—4 
HDR2, G-5 
HDR3, G-6 
File I/0 
coordination, 2-42 
status block, 2-44 
File identification, 5-3 
FDB, 3-10 
field, 2-34 
File identifier 
processing by Files-ll (tape), 
File label 
tape, G-l 
File macro, 3-1 
access privileges, 3-3 
error routine, 3-2 
File name 
-PARSE routine, 4-13 
~-PRSFN routine, 4-15 
tape 
Radix-50 conversion, 4-18 
File number, 5-3 
File open 
append, 2-15 
by ID, 2-34 
for file access, 3-16 
lock on close, 2-16 
modify, 2-15 
no supersede, 2-15, 3-16, 3-17 
read access, 2-15 
shared access, 2-15 
tape position, 2-16 
temporary, 2-15 
update, 2-15 
write access, 2-15 
File operation, error codes, I-1l 
File owner word, 4-5 
read, 4-6 
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File owner word (Cont.) Filename block 
write, 4-6 default directory information 
File pointer routine, 4-20 (Cont.) 
File position -GTDID routine, 4-20 
by byte, 2-11 delete file, 4-26 
Save, 4-22 directory information 
to byte -GTDIR routine, 4-19 
-POINT routine, 4-21 initializing, 2-35 
to record local offset definition, 2-33 
-POSRC routine, 4-21 Manually initializing, 2-36 
File processing completion N.DID field 
CLOSES macro, 2-8 : -PARSE routine, 4-12 
File protection word, 4-4, 4-5 N.DVNM field, 4-16 
File random I/0, 2-20 N.NEXT 
File read-ahead -PARSE routine, 4-14 
FD.RAH parameter, 3-11 N.STAT word 
File record -PARSE routine, 4-14 
attribute, 2-6 NBOFSL macro, 2-33 
File rename routine, 4-23 NMBLKS macro, 2-31 
File sequence number, 2-7, 5-3 open file by, 3-14 
File space preallocation, 2-20 OPENSx macro, 2-35 
File specification -PARSE routine 
definition, 1-3 disk, 4-10 
device, 1-14 N.DID field, 4-12 
~PRSDV routine, 4-15 N.FID field, 4-12 
directory, 1-14 tape, 4-10 
-PRSDI routine, 4-15 Filename block routine, 4-7, 4-19 
dynamic processing Filename string descriptor, 2-29 
SYSLIB, 2-34 Files-ll structure, 5-1l 
generation, 1-17 -FIND routine, find directory 
logical name expanding, 4-9 entry, 4-16 
logical name merging, 4-9 -FINIT routine, initialize before 
logical name parsing, 4-9 -PARSE routine, 4-10 
magnetic tape, 1-16, 1-17 FINITS macro 
name, 1-15 FSR initialization 
syntax description, 1-13 run-time, 2-40 
type, 1-15 Fixed-length record 
unit PUTS macro 
-PRSDV routine, 4-15 block boundary, 3-27 
version, 1-16 block buffer, 3-27 
within program, 2-27 Flush buffer routine, 4-28 
File Storage Region -FLUSH routine, flush buffer, 
See FSR 4-28 
File structure, 5-l FNB 
tape, G-9 definition, 1-2 
user, 5-2 N.XXXX field, B-l 
virtual blocks, 5-2 FO.APD value, open file for 
File trailer label (tape), G-9 append, 3-17 
File type FO.MFY value, open file for 
-PARSE routine, 4-13 modify, 3-17 
-PRSFN routine, 4-15 FO.RD value, open file for read, 
File version 3-17 
-PARSE routine, 4-13 FO.UPD value, open file for 
-PRSFN routine, 4-15 update and extend, 3-17 
File window pointer FO.WRT value 
number, 2-16 open file for write and create, 
Filename block 3-17 
See also FNB FORTRAN carriage-control 
default, 2-31, 3-15 record attribute, 3-8 
file-open, 2-14 FSR 
initialization, 2-15 as data structure, 1-4 
OFNBSx macro, 3-15 definition, 1-3 
specifying, 2-28 general description, 1-5 


default directory information 
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FSR 

increasing size 
FORTRAN, 2-42 
MACRO-11, 2-41 

initalization 
FINITS macro, 

initialization 
FSRSZS macro, 

record 1/0, 2-38 


2-40 


2-37 


multiple buffering, 2-38 

fsx 

INITIALIZATION, 2-37 
FSR block buffer 

block boundary, 3-26 

locate mode, 3-21, 3-27 

pool space, 2-39 

space allocation, 2-20 
SSFSR1, 1-5 
SSFSR2 

default UIC, 4-4 

file owner word, 4-5 

file protection word, 4-4 


general description, 1-6 
FSRSZS macro, FSR initialization, 
2-37 


GCML, 6-1, 6-2 
control block 
allocate, 6-3 
define bit values, 
define offsets, 6-5 
initialize, 6-3 
routine, run-time error, 
usage, 6-13 
GCMLS$ macro, 
GCMLBS$ macro, 6-3 
GCMLDS macro, 6-5 
Get command line 
See also GCML 
Get command line macro, 
GETS macro, 1-8, 3-1 
example, 3-20 
FD.RWM parameter, record I/O, 
2-10 
FDB, file processing, 3-21 
file processing, 3-19 
locate mode, 3-21 
move mode, 3-21 
format, file processing, 3-19 
GETSR macro, 3-1 
file processing 
read logical record, random 
mode, 3-22 
GETSS macro, 3-1 
file processing 
read logical record, 
sequential mode, 
Global symbol, FDB macro, 
GLUNS directive summary, 
GMCRS directive summary, 
-GTDID routine, 4-19 
-GTDID routine, default directory 
information, 4-20 
-GTDIR routine, 4-19 


6-5 


6-9 
6-9 


6-9 


3-24 
2-26 

C-1 

C-1 


_H. PROJ, 


~GTDIR routine, 

information, 4-19 
H.CKSM, 
H.FLEV, 
H.FNUM, 
H.FOWN, 
H.FPRO, 
H.FSEQ, 
H.IDOF, 
H.MPOF, 
H.PROG, 


checksum word, 


member number, 
group number, 
H.SCHA, 


F-3 


structure level, F-1l 
file number, F-1l 

offset to file owner, F-1l 
file protection code, F-1l 
file sequence number, F-1l 
header area, F-1l 

map area offset, F-1 


F-1 
F-1 


characteristics, F-2 


user-controlled file 


characteristics, F-l 
H.UFAT, user file attributes, F-2 


Header area, 5-3 


file header block, F-3 


file 
file 
file 
file 
file 


number, F-3 


characteristics, F-4 


identification area, F-3 
map area offset, F-3 
structure level, F-3 


user file attributes 


file characteristics, F-4 


Header block 
file, 5-3 
Home block, E-1l 
I.CRDT, 
I.CRTI, 
I. EXDT, 
I.FNAM, 
I.FTYP, 
I.FVER, 
I.RVDT, 
I.RVNO, 
I.RVTI, 

I/O 
block operation, 1-7 
coordination 

event flag, 2-43 

file operation, 2- 
data-transfer mode, 
directive summary, C 
locate mode, 1-9, l- 
move mode, 1-9 


creation date, 
creation time, 


file type, F-2 
revision date, 


revision time, 


preparation, FCS macro, 


record 
big buffering, 1-1 
multiple buffering 


F-2 
F-2 


expiration date, F-2 
identification area, F-2 


file version number, 


F-2 


revision number, F-2 


F-2 


42 
1-9 


-1 


10 
2-1 


a 
, 1-10 


record operation, 1-8 


synchronization, 1-7 
event flag, 2-18, 
wait for completion 
block 1/0, 3-37 
I/O macro 
AST service routine, 
FCS, 2-1 
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2-45, 


insert directory 


system-controlled file 


owner information, F-3 
protection code, F-4 
sequence number, F-3 


F-2 


2-46 


INDEX 


I/O macro (Cont.) 
FDB, 2-2 
I/O program example, D-1l 
I/O status block 
block 1/0, 2-13 
defined in task, 2-45 
file I/O, 2-44 
Identification area, 5-4 
file header block, F-4 
creation date, F-5 
creation time, F-5 
expiration date, F-5 
file version number, F-4 
filename, F-4 
filetype, F-4 
revision date, F-4 
revision number, F-4 
revision time, F-5 
Index file, 5-2 
bit map, E-2 
format, E-1l 
header, E-2 
ISTATS macro, 7-1, 7-2 


Keyword recognition, transition 
table, 7-9 


Library option, FCS, K-1 
Line-feed character 
record attribute, 3-8 
Local symbol 
FDB macro, 2-27 
Locate mode, 1-9, 1-10, 
file processing, 3-27 
FSR block buffer, 3-27 
GETS macro, 3~19, 3-21 
PUTS macro, 3-24, 3-28 
record attribute, 3-9 
task record buffer, 3-27 
Logical block, 5-2 
file device, 1-7 
Logical name, 1-18 
specifying, 1-19 
using, 1-19 
Logical name translation, 4-8 
ASSIGN command, 4-8 
expanding file specification 
string, 4-9 
FDB extension, 4-14 
iterative, 4-8 
merging file specification, 4-9 
name expansion 
~-EXPLG module, 4-14 
parse file specification, 4-9 
-PARSE routine 
device and unit, 4-11 
process, 4-9 
-PRSDV routine, 4-15 
LUN, assign with .ASLUN routine, 
5 


2-10 


M.CTSZ, retrieval pointer block 
count field size, F-2 


M.EFNU, extension file number, 
F-2 

M.EFSQ, extension file sequence 
number, F-2 

M.ERVN, extension relative volume 
number, F-2 

M.ESQN, map area, F-2 

M.LBSZ, retrieval pointer logical 
block number field size, F-2 

M.MAX, available retrieval 
pointer words, F-3 


M.RTRV, retrieval pointer start, 


F-3 
M.USE, retrieval pointer word 
count, F-3 
Macro 
global symbol, 2-26 
local symbol, 2-27 
run-time 
exceptions, 2-22 
FDB address, 2-24 
initialization, 2-21 
MAG, G-ll 
MAG task error messages, G-15 
Map area, 5-4 
file header block, F-5 
Mark file for delete, 4-25 
»-MARK routine, save file position, 
4-22 
Master File Directory, 5-2 
-MCALL directive, 2-2 
MFD, 5-2 
MFD header, E-2 
Move mode, 1-9 
GETS macro, 3-19, 3-21 
PUTS macro, 3-24, 3-26 
-MRKDL routine, mark temporary 
file for delete, 4-25 
Mutiple file operation, 5-6 


N.ANM1 field, ANSI filename 
string, B-4 

N.ANM2 field, remainder of ANSI 
filename string, B-4 

N.DID field, .PARSE routine, 4-12 

N.DID field, directory 
identification, B-2 

N.DVNM field, 4-16 

N.DVNM field, ASCII device name, 
B-2 

N.DVNM field, ASCII tape device 
name, B-4 

N.FID field 

-FIND routine, 4-16 
-PARSE routine, 4-12 

N.FID field, file identification, 
B-l, B-4 

N.FNAM field, file name, B-1l 

N.FTYP field, file type, B-1l 

N.FVER field, file version number, 
B-1 

N.FVER field, tape file version 
number, B-4 
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N.NEXT field, context for next 
FIND, B-2 

N.NEXT field, tape context for 
next .FIND, B-4 

N.STAT field, filename block 
status word, B-1 


N.STAT field, tape filename block 


status word, B-4 
N.UNIT field 


FNB (tape), B-4 
N.UNIT field, unit number field, 
B-2 


NBOFSL macro, 2-33 
NMBLKS macro 
default filename block, 


example, 2-33 


2-31 


OFIDS macro, 3-l 
OFIDS$x macro, file processing, 
3-13 
OFNBS macro, 
OFNBSx macro 

dataset descriptor, 


3-1 


3-15 


default filename block, 3-15 
file processing, 3-14 
Open file 
by filename block, 3-14 
by ID, 2-34, 3-13 
existing, 3-9 
for access, 3-16 
for modify, 3-17 
for read, 3-17 
for update and extend, 3-17 
new, 3-9 
no supersede, 3-16, 3-17 
processing, 3-3 
OPENS 
example, 5-9 
macro, 3-1 


macro, file processing, 3-16 
OPENSR 


example, 5-8 

macro, shared access, 1-13 
OPENSx macro 

file processing, 3-2 , 3-7 


format, file operations, 3-5 


OPNSS macro, 3-1 


OPNSSR macro, shared access, 1-12 


OPNSSx macro, file processing, 


OPNTS macro, 3-1 
OPNTSD macro, 3-13 
OPNTSW macro, file processing, 


3-12 
Owner ID field 
tape, G-2 


-PARSE routine 
device and unit translation, 
4-11 


logical name translation, 4-10 


Parser program 
TPARS, 7-12 


INDEX 


Parser program 
TPARS (Cont.) 
processing steps, 
Parsing 
command line, 7-1 
complex command lines, 
UFD, 7-14 
-POINT routine 
file byte position, 2-11 
position file to byte, 4-21 
-POSIT routine, return record 
position, 4-22 
Position to next file 


7-14 


7-19 


tape, 5-5 
-POSRC routine, position file to 
record, 4-21 
»~PPASC routine, convert UIC to 
ASCII, 4-7 


PRINT command, 8-2 
-PRINT routine, error handling, 
8-2 
-PRINT subroutine, 
PRINTS macro, 8-1 
error handling, 


8-1 


8-2 


Print, open file on LP:, 8-2 

Program example I/O, D-1l 

Program section 

TPARS, 7-10 

-PRSDI routine, fill in directory 
information, 4-15 

-PRSDV routine, fill in 
device/unit information, 4-15 

-PRSFN routine, fill in file 
name, type, version, 4-15 

PUTS macro, 1-8, 3-l, 3-26 


FD.RWM parameter 
record I/0, 2-10 
FDB, file processing, 

file processing 
locate mode, 3-27 
write logical record, 3-24 
file truncate, 2-11 
fixed-length record, 3-26 
block boundary, 3-27 
block buffer, 3-27 
format, 3-24 
locate mode, 3-24, 3-28 
move mode, 3-24, 3-26 
no truncate, 2-10 
sequenced record, 3-24 
task record buffer, 3-26 
variable-length record, 
block boundary, 3-27 
PUTSR macro, 3-l 
example, 3-29 
file processing 
write logical record, random 
mode, 3-28 
random mode 
locate mode execution, 
PUTSS macro, 3-1 
file processing 
write logical record, 
sequential mode, 3-30 


3-25 


3-26 


3-29 
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QIO execution routine, 4-23 
QIO$ directive summary, C-l 
QIOMAC.MAC error codes, I-l 
QIOWS directive summary, C-2 


R.FIX 
file attribute, 2-5 


parameter, fixed-length records, 


R.SEQ 
file attribute, 2-6 
parameter, sequenced records, 
R. VAR 
file attribute, 2-6 
parameter, variable-length 
records, 3-8 
Random access, 2-10 
Random access mode, 3-21 
Random access mode, record 
attribute, 3-9 
Random I/0, 2-20 
Random mode 
PUTSR macro 
locate mode execution, 3-29 
write logical record, 3-28 
RCMLS macro, 6-12 
RCSTS$ directive summary, C-2 
RCVD$ directive summary, C-3 
RCVXS$ directive summary, C-3 
-RDFDR routine, read SSFSR2 
default directory string, 4-2 
~RDFPP routine, read SSFSR2 
default file protection word, 
4-5 
e-RDFUI routine, read default UIC, 
4-3, 4-4 
Read SSFSR2, default directory 
string, 4-2 
Read access 
file open, 2-15 
shared, 1-13 
Read default UIC, 4-4 
Read file owner word, 4-6 
Read file protection word 
default, 4-5 
Read logical record 
file processing, 3-19 
random mode 
file processing, 3-22 
sequential mode, 3-24 
Read virtual block 
file processing, 3-30 
READS macro, 1-7, 3-1 
block access, 2-12 
end-of-file, 3-33 
example, 3-32 
FD.RWM parameter 
block I/O, 2-10 
FDB, file operation, 3-33 
file processing 
read virtual block, 3-30 
format 
file processing, 3-31 


READS macro (Cont.) 
virtual block number, 3-31 
Read-ahead file processing, 2-19 
Record 
fixed-length 
PUTS macro, 3-26 
R.FIX parameter, 3-8 
sequenced 
PUTS macro, 3-24 
R.SEQ parameter, 3-8 
“variable-length, 1-6 
PUTS macro, 3-26 
R.VAR parameter, 3-8 
Record access initialization, 
2-10 
Record attribute, 2-6, 3-8 
FD.BLK parameter 
block boundary crossing, 3-9 
* FD.CR, 2-6 
FD.CR parameter 
line-feed character, 3-8 
FD.FTN parameter 
FORTRAN carriage-control, 3-8 
FD.RAN parameter 
random access mode, 3-9 
FD.RPN parameter 
carriage-control word, 3-9 
locate mode, 3-9 
sequential mode, 3-9 
FD.RTN, 2-6 
FD.RWM parameter 
process with block I/0, 3-9 
Record buffer 
task 
locate mode, 3-27 
Record format 
tape, 5-4 
Record I/0, 2-10 
FSR, 2-38 
FSRZ 
multiple buffering, 2-38 
locate mode, FD.PLC parameter, 
3-6 
macro, 2-10 
mode, 1-9 
multiple buffering, 1-10 
operation, 1-8 
random, FD.RAN parameter, 3-6 
synchronization, event flag, 
2-18 
Record size 
FDB, 3-9 
fixed length, 2-8 
largest, 2-8 
-REMOVE routine, delete directory 
entry, 4-19 
-RENAME routine, rename file, 
4-23 
Rewind 
on close or open, 2-16 
volume, 5-5 
-RFOWN routine, read SSFSR2 file 
owner word, 4-6 
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SRONLY 
state table, 7-2 
Run-time initialization 
FSR 
FINITS macro, 2-40 


S.BFHD, FSR block buffer header 
size, J-l 

S.FATT, FDB file attribute area 
size, J-1 

S.FDB, FDB size, J-1l 

S.FNAM, file name size, J-1l 

S.FNB, filename block size in 
bytes, J-l 

S.FNBW, filename block size in 
words, J-l 

S.FNTY, file name and type size, 
J-1 

S.FSR2, FSR2 (impure area) size, 
J-1 

S.FTYP, file type size, J-1l 

S.HDHD, header area size, F-2 


S.IDHD, identification area size, 


F-2 
S.MPHD, map area size, F-3 
S.NFEN, complete file name size, 
J-1 

SC.MDL, bad data block 

user-controlled file 

characteristic, F-4 

SC.MDL, file marked for delete 

user-controlled file 

characteristic, F-4 

SDATS directive summary, C-3 
SDRCS$ directive summary, C-3 
SDRPS$ directive summary, C-4 
Security information 

DELETS macro, 3-39 
Sequenced mode 

GETS, 3-19 
Sequential file, 2-10 
Sequential mode 

FD.INS parameter, 3-6 

record attribute, 3-9 

write logical record, 3-30 
Shared access 

file, 1-12 

file open, 2-15, 3-12 
Single file operation, 5-6 
SMSGS$ directive summary, C-5 
Special character 

State table, 7-8 
Spooling, 8-1 

-PRINT subroutine, 8-1 
SSTATE program section, 7-2 
State table, 7-1 

arrangement of syntax types, 

initializing, 7-2 

rejecting transitions, 7-18 

special character, 7-8 

using subexpressions, 7-18 
STATES macro, 7-1, 7-2 
Statistics block, H-1l 


INDEX 


Storage map, file header, E-2 
Subexpression, parsing complex 
command lines, 7-19 
Syntax 
element, defining, 7-2 
state table, 7-7 


Tab 
ignoring in command line, 7-8 
Table Driven Parse 
See TPARS 
Tape 
ANSI file structure, 5-1 
control task, G-ll 
data format, 1-7 
end-of-file label, G-9 
end-of-volume label, G-8 
file processing, 5-4 
fixed length records, 1-7 
owner ID field, G-2 
position to next file, 5-5 
position, file open, 2-16 
positioning, G-17 
processing example, 5-8 
read, indirect command file, 
G-19 
record format, 5-4 
translation, G-17 
unlabeled, G-16 
block size, G-16 
user file label, G-9 
user volume label, G-3 
variable length record, 1-7 
volume access, 5-5 
volume label, G-l 
Tape file 
attributes, specifying, G-17 
header block, G-10 
header label, G-3 
header label (HDR1), G- 
header label (HDR2), G- 
header label (HDR3), G- 
identifier processing, 
label, G-l 
structure, G-9 
Tape handling 
end-of-tape, G-10 
Tape standard, ANSI, G-l 
Task 
spooling print job, 8-1 
Task buffer descriptor, 3-10 
Task record buffer, 3-21 
TPARS 
built-in variable, 7-5 
coding, 7-1, 7-7 
command line parsing, 7-1 
creating parser program, 7-12 
invoking, 7-11 
macro, 7-l 
options word, 7-11 
program section, 7-10 
programming examples, 7-14 
register usage, 7-11 
state table, 7-1 


4 
5 
6 
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TPARS (Cont.) 
Subexpression, 7-7 
transition, 7-1 
TRANS macro, 7-1, 7-3 
Transition table 
recognition of keyword, 7-9 
-TRNCL routine, truncate file, 
4-25 


UC.CON, contiguous file 
user-controlled file 
characteristic, F-4 
UC.DLK, file improperly closed 
user-controlled file 
characteristic, F-4 
UFD, 5-2 
UIC, 5-2 
aay te conversion, 4-6, 
-7 
read/write defaults, 4-3, 4-4 
Unit information 
~PRSDV routine, 4-15 
Unit number field, 2-34 
Unlabeled tape, G-16 
Unlabeled tape block size, G-16 
User file attributes 
header area 
file characteristics, F-4 
User File Directory, 5-2 
User file label (tape), G-9 
User Identification Code 
See UIC 
User volume label 
tape, G-3 


Variable-length record 

block boundary 

PUTS macro, 3-27 

Virtual block 

file device, 1-7 

file extension, 2-9 
Virtual block number 

READS macro, 3-31 

WRITES macro, 3-35 
Volume 

default extend size, 2-9 
Volume label 

tape, G-l 

user, G-3 

Volume rewind, 5-5 
VRCDS$ directive summary, C-5 
VRCSS directive summary, C-5 
VRCXS directive summary, C-6 
VSDAS directive summary, C-6 
VSRCS directive summary, C-6 
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WAITS macro 
file processing, 3-1 
block I/O completion, 3-37 
format 
file operations, 3-37 
with READS and WRITES, 3-37 
with READS or WRITES, 3-30 
e-WDFPP routine, write SSFSR2 
default file protection word, 
4-5 
-WDFR routine, write SSFSR2 
default directory string, 4-3 
eWDFUI routine, write default UIC, 
4-3, 4-4 
eWFOWN routine, write SSFSR2 file 
owner word, 4-6 
Wild card 
file name, 4-18 
file type, 4-18 
Window pointer 
number, 2-16 
Write 
file owner word, 4-6 
Write SSFSR2 
default directory string, 4-3 
Write access 
file open, 2-15 
shared, 1-12 
Write default UIC, 4-4 
Write file protection word 
default, 4-5 
Write logical record 
file processing, 3-24 
random mode, 3-28 
sequential mode, 3-30 
Write virtual block 
file processing, 3-34 
WRITES macro, 1-7, 3-1 
block access, 2-12 
example, 3-36 
extending file, 3-36 
FD.RWM parameter 
block I/0, 2-10 
FDB, 3-36 
file processing, 3-34 
write virtual block, 3-34 
format, 3-34 
virtual block number, 3-35 
Write-behind file processing, 
2-19 
Write-behind operation, FD.WBH 
parameter, 3-11 


-XQIO routine, execute QIO, 4-23 
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